/ Hex Artifact Content
Login

Artifact 39cc33bb08897c748fe3383c29ccf56585704177:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5760: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5770: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5780: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5790: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
57a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
57b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
57c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
57d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5800: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5810: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5820: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5830: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5850: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5860: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5870: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
58b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
58d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5900: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5910: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5920: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5940: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5950: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5960: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5980: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5a30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5aa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5af0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5b30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5bb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bf0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5c30: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cb0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5cd0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ce0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d00: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5d10: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5d20: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d50: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d60: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d70: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5da0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5dc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5dd0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5df0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5e00: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5e10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5e20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5e30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e50: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e70: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e80: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e90: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5ea0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5eb0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5ec0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5ed0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ee0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5ef0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5f00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5f20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5f30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5fa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5fb0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5fc0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5fd0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fe0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5ff0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6000: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6010: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6020: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6030: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6040: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6050: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6060: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6070: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6080: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6090: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
60a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
60b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
60c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
60d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6100: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6110: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6120: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6130: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6140: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6150: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6160: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6170: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6180: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6190: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
61a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
61b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
61c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
61d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6200: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6220: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6230: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6240: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6250: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6260: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6270: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6280: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6290: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
62a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
62b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
62c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62f0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6300: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6320: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6370: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
63a0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
63b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
63c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
63d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63e0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6400: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6410: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6430: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6440: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6450: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6460: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6470: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6480: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
64a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
64b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
64c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64f0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6510: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6520: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6540: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6550: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6560: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6570: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6580: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6590: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
65a0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
65b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
65c0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
65d0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65e0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65f0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6600: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6610: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6620: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6650: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6660: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6670: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6680: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6690: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
66b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
66c0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66e0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66f0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6700: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6710: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6720: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6730: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6740: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6760: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6770: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6780: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6790: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
67a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
67b0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
67c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67d0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67e0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67f0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6800: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6810: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6830: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6840: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6850: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6860: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6870: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6880: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6890: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
68a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
68b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
68c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
68d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6900: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6920: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6930: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6940: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6950: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6960: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6970: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6980: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
69b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
69d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6a00: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6a10: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6a20: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6a30: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a40: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a80: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a90: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6aa0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6ab0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ac0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6ad0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ae0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6af0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6b00: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6b10: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6b20: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6b30: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b40: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b50: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b60: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b70: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b80: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b90: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6ba0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6bb0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6bc0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6bd0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6be0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bf0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6c10: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6c20: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6c30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c40: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c50: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c70: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c90: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6ca0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6cb0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6cc0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6cd0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ce0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cf0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6d00: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6d10: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6d20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6d30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d40: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d50: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d60: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d70: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d80: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d90: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6da0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6db0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6dc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6de0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6df0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6e00: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6e10: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6e20: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e50: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e60: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e70: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e80: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e90: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6ea0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6eb0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6ed0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ee0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6ef0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6f00: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6f10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6f20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6f30: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f50: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f60: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f70: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f90: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6fa0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6fb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6fc0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6fd0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fe0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6ff0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7000: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7010: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7020: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7030: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7040: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7050: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7060: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7070: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7080: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7090: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
70a0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
70b0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
70c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
70d0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70e0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70f0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7100: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7110: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7120: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7130: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7140: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7150: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7160: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7170: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7180: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7190: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
71a0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
71b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
71c0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
71d0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71e0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71f0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7200: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7230: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7240: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7250: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7260: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7270: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7280: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7290: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
72a0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
72b0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
72c0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
72d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72f0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7300: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7310: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7320: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7330: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7340: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7350: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7360: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7370: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7380: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7390: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
73b0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
73d0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73f0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7400: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7410: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7420: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7430: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7440: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7450: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7460: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7470: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7480: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7490: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
74a0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
74b0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
74c0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
74d0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74e0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74f0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7500: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7510: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7520: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7530: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7540: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7550: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7560: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7570: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7580: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7590: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
75a0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
75b0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
75c0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
75d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75e0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7600: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7610: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7620: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7630: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7640: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7650: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7660: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7670: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7680: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7690: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
76a0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
76b0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
76c0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
76d0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76e0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76f0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7700: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7710: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7720: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7730: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7740: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7750: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7760: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7770: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7780: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7790: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
77a0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
77b0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
77c0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
77d0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77e0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7800: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7810: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7820: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7830: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7840: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7850: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7860: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7870: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7880: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7890: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
78a0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
78b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
78c0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
78d0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78e0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7900: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7910: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7920: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7930: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7940: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7950: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7960: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7970: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7980: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7990: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
79a0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
79b0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
79c0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
79d0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7a00: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7a10: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7a20: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7a30: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a40: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a50: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a60: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a80: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7aa0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ae0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7b10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b20: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b40: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b60: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7ba0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7bb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7bc0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7bd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bf0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7c00: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7c10: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7c20: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c40: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c50: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c60: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c70: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c80: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c90: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7ca0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7cb0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7cc0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7cd0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cf0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7d00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7d10: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7d20: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7d30: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d40: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d50: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d60: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d70: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d80: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d90: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7da0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7db0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7dc0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7dd0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7de0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7df0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7e00: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7e10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7e20: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7e30: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e40: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e50: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e60: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e70: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e80: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e90: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7ea0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7eb0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7ec0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7ed0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7f00: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7f10: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7f20: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7f30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f60: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f90: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7fa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7fb0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7fc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7fd0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fe0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7ff0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8000: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8010: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8020: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8030: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8040: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8050: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8060: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8070: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8080: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8090: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
80a0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
80b0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
80d0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80e0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80f0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8100: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8110: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8120: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8130: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8150: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8160: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8170: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8180: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8190: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
81a0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
81b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
81c0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
81d0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81f0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8200: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8210: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8220: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8230: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8240: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8250: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8260: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8270: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8280: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8290: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
82a0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
82b0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
82c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
82d0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82f0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8300: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8310: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8320: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
8330: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8340: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8350: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8360: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8370: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8380: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8390: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
83a0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
83b0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
83c0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
83d0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8400: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8420: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8430: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8450: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8460: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8470: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8480: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8490: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
84a0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
84b0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
84c0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
84d0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8500: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8510: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8520: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8530: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8540: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8550: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8560: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8570: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8580: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8590: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
85a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
85b0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
85c0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
85d0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85e0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8610: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8630: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8640: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8650: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8660: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8670: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8680: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8690: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
86a0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
86b0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
86c0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
86d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86e0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86f0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8700: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8710: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8720: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8730: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8740: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8750: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8760: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8770: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8780: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8790: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
87a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
87b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
87c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
87d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87e0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87f0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8800: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8810: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8820: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8830: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8840: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8850: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8860: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8870: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8890: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
88a0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
88b0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
88c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
88d0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88e0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88f0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8900: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8910: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8920: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8930: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8940: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8950: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8960: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8970: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8980: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8990: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
89a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
89b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
89c0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
89d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89e0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89f0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8a00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8a10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a20: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8a30: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a40: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a50: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a60: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a80: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a90: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8aa0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8ab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8ac0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8ad0: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8af0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8b00: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8b10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8b20: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8b30: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b40: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b50: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b60: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b80: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b90: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8ba0: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8bb0: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8bc0: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8bd0: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8be0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bf0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8c00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8c10: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8c20: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8c30: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c40: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c60: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c70: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c80: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8ca0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8cb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8cc0: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8cd0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ce0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cf0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8d00: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8d10: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8d20: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8d30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d40: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d50: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d70: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d90: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8da0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8db0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8dc0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8dd0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8de0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8df0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8e00: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8e10: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8e20: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8e30: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e50: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e60: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e70: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e80: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e90: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8ea0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8eb0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8ec0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8ed0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ee0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8ef0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8f00: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8f10: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8f20: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8f30: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f40: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f50: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f60: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f70: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f90: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8fa0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8fb0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8fc0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8fd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fe0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8ff0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9000: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9010: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9020: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9030: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9040: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9050: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9060: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9070: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9080: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9090: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
90a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
90b0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
90c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
90d0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90e0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90f0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9100: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9110: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9120: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9130: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9140: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9150: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9160: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9170: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9180: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9190: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
91a0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
91c0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
91d0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91e0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91f0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9200: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9210: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9220: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9230: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9240: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9250: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9260: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9270: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9280: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9290: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
92a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
92b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
92c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
92d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9300: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9310: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9320: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9330: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9340: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9350: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9360: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9370: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9380: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9390: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
93a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
93b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
93c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
93d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9400: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9410: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9420: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9430: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9440: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9450: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9460: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9480: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9490: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
94a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
94b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
94c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
94d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9500: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9510: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9520: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9530: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9550: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9560: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9570: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9580: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9590: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
95a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
95b0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
95c0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
95d0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95e0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95f0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
9600: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
9610: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
9620: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
9630: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9640: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9650: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9660: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9670: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9690: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
96a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
96b0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
96c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
96d0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96e0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96f0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9700: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
9710: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
9720: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9730: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9740: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9750: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9760: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9770: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9780: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9790: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
97a0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
97b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97c0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
97d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97e0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97f0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9800: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9810: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
9820: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
9830: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9840: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9850: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9860: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9870: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9880: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9890: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
98a0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
98b0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
98c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
98d0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98f0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9900: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9910: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
9920: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
9930: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9940: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9950: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9960: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9970: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9980: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
99a0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
99b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
99c0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
99d0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99f0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9a00: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9a10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9a20: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9a30: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a40: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a50: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a60: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a70: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a80: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a90: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9aa0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9ab0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9ac0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9ad0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ae0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9af0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9b00: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9b10: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9b20: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9b30: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b40: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b50: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b70: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b80: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9ba0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9bb0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9bc0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9bd0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9be0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9c00: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9c10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9c20: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9c30: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c50: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c60: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c70: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c80: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9ca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9cb0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9cc0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9cd0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ce0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cf0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9d00: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9d10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9d20: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9d30: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d50: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d60: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d70: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d80: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d90: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9da0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9db0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9dc0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9dd0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9de0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9df0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9e00: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9e10: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9e20: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9e30: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e40: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e50: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e60: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e70: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e80: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e90: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9ea0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9eb0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9ec0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9ed0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ee0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9ef0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9f00: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9f10: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9f20: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f60: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f70: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f80: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f90: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9fa0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9fb0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9fc0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9fd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a000: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a010: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a020: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a030: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a040: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a050: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a060: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a070: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a080: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a090: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a0a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a0b0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a0c0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a0d0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a100: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a110: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a120: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a130: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a140: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a150: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a160: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a170: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
a180: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a190: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a1a0: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
a1b0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
a1c0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a1d0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
a1e0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
a1f0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
a200: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
a210: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
a220: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
a230: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
a240: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
a250: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
a260: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
a270: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
a280: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
a290: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
a2a0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
a2b0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
a2c0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
a2d0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
a2e0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
a2f0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
a300: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
a310: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
a320: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
a330: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
a340: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
a350: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
a360: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
a370: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
a380: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
a390: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
a3a0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
a3b0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
a3c0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
a3d0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
a3e0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
a3f0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
a400: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
a410: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
a420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a430: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
a440: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
a450: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a470: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
a480: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
a490: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a4a0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
a4b0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
a4c0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
a4d0: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
a4e0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
a4f0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
a500: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
a510: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
a520: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
a530: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
a540: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
a550: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
a560: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
a570: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a580: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a590: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
a5a0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
a5b0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
a5c0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
a5d0: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
a5e0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
a5f0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
a600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a610: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
a620: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
a630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
a640: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
a650: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
a660: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
a670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
a680: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
a690: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
a6a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
a6b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
a6c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
a6d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
a6e0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
a6f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
a700: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
a710: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
a720: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
a730: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
a740: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
a750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a760: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
a770: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
a780: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a790: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
a7a0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
a7b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a7c0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
a7d0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
a7e0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a7f0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a800: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
a810: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
a820: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a830: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a840: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a850: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
a860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a870: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
a880: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
a890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a8a0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a8b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
a8c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a8d0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
a8e0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
a8f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a900: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
a910: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
a920: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
a930: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
a940: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
a950: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
a960: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
a970: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
a980: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
a990: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
a9a0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
a9b0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
a9c0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
a9d0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
a9e0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
a9f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
aa00: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
aa10: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
aa20: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
aa30: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
aa40: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
aa50: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
aa60: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
aa70: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
aa80: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
aa90: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
aaa0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
aab0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
aac0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
aad0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
aae0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
aaf0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
ab00: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
ab10: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
ab20: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
ab30: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
ab40: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
ab50: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
ab60: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
ab70: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
ab80: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
ab90: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
aba0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
abb0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
abc0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
abd0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
abe0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
abf0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
ac00: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
ac10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
ac20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
ac30: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
ac40: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
ac50: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
ac60: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
ac70: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
ac80: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
ac90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
aca0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
acb0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
acc0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
acd0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
ace0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
acf0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
ad00: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
ad10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
ad20: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
ad30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ad40: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ad50: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ad60: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
ad70: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
ad80: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
ad90: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
ada0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
adb0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
adc0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
add0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
ade0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
adf0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
ae00: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
ae10: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
ae20: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
ae30: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
ae40: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
ae50: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
ae60: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
ae70: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
ae80: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
ae90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
aea0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
aeb0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
aec0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
aed0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
aee0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
aef0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
af00: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
af10: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
af20: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
af30: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
af40: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
af50: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
af60: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
af70: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
af80: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
af90: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
afa0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
afb0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
afc0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
afd0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
afe0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
aff0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
b000: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
b010: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
b020: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
b030: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
b040: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
b050: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
b060: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
b070: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b080: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
b090: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
b0a0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
b0b0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
b0c0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b0d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
b0e0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
b0f0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
b100: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
b110: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
b120: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
b130: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
b140: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
b150: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
b160: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
b170: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
b180: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
b190: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
b1a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b1b0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
b1c0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
b1d0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
b1e0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
b1f0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
b200: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
b210: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
b220: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
b230: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
b240: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
b250: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
b260: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
b270: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
b280: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
b290: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
b2a0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
b2b0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
b2c0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
b2d0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
b2e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
b2f0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
b300: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
b310: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
b320: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
b330: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
b340: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
b350: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b360: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
b370: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
b380: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
b390: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
b3a0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
b3b0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
b3c0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
b3d0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
b3e0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
b3f0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
b400: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
b410: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
b420: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
b430: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
b440: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b450: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
b460: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
b470: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
b480: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
b490: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
b4a0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
b4b0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
b4c0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
b4d0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
b4e0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
b4f0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
b500: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
b510: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
b520: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
b530: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
b540: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
b550: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
b560: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
b570: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
b580: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
b590: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
b5a0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
b5b0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
b5c0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
b5d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
b5e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
b5f0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
b600: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
b610: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
b620: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
b630: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
b650: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b660: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
b670: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b680: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
b690: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b6a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
b6b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
b6c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
b6d0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
b6e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b6f0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
b700: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b710: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
b720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b730: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
b740: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
b750: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
b760: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
b770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
b780: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
b790: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
b7a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
b7b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b7c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
b7d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
b7e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
b7f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
b800: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
b810: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
b820: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
b830: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
b840: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
b850: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
b860: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
b870: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
b880: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
b890: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
b8a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
b8b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
b8c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
b8d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
b8e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
b8f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
b900: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
b910: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
b920: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
b930: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
b940: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
b950: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
b960: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
b970: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
b980: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
b990: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
b9a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
b9b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
b9c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
b9d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
b9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
b9f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
ba00: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ba10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
ba20: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
ba30: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
ba40: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
ba50: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
ba60: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
ba70: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ba80: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
ba90: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
baa0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
bab0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
bac0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
bad0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
bae0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
baf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
bb00: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
bb10: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
bb20: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
bb30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
bb40: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
bb50: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
bb60: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
bb70: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
bb80: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
bb90: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
bba0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
bbb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
bbc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
bbd0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
bbe0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
bbf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
bc00: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
bc10: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
bc20: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
bc30: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
bc40: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
bc50: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
bc60: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
bc70: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
bc80: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
bc90: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
bca0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
bcb0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
bcc0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
bcd0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
bce0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
bcf0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
bd00: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
bd10: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
bd20: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
bd30: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
bd40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
bd50: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
bd60: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
bd70: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
bd80: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
bd90: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
bda0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
bdb0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
bdc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
bdd0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
bde0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
bdf0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
be00: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
be10: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
be20: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
be30: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
be40: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
be50: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
be60: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
be70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
be80: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
be90: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
bea0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
beb0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
bec0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
bed0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
bee0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
bef0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
bf00: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
bf10: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
bf20: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
bf30: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
bf40: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
bf50: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
bf60: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
bf70: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
bf80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
bf90: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
bfa0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
bfb0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
bfc0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
bfd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bfe0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
bff0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
c000: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
c010: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
c020: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
c030: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
c040: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
c050: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
c060: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
c070: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
c080: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
c090: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
c0a0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
c0b0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
c0c0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
c0d0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
c0e0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
c0f0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
c100: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
c110: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
c120: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
c130: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
c140: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
c150: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
c160: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
c170: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
c180: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c190: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
c1a0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
c1b0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
c1c0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
c1d0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
c1e0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
c1f0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
c200: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
c210: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
c220: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c230: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
c240: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
c250: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
c260: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
c270: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
c280: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
c290: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
c2a0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
c2b0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
c2c0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
c2d0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
c2e0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
c2f0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
c300: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
c310: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
c320: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
c330: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
c340: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
c350: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
c360: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
c370: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
c380: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
c390: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
c3a0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
c3b0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
c3c0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
c3d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
c3e0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
c3f0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
c400: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
c410: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
c420: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
c430: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
c440: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
c450: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c460: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
c470: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
c480: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
c490: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
c4a0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
c4b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
c4c0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
c4d0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
c4e0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
c4f0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
c500: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c510: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
c520: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
c530: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
c540: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
c550: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
c560: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
c570: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
c580: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
c590: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
c5a0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
c5b0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
c5c0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
c5d0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
c5e0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
c5f0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
c600: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
c610: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
c620: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
c630: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
c640: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
c650: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
c660: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
c670: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
c680: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
c690: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
c6a0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
c6b0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
c6c0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
c6d0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
c6e0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
c6f0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
c700: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
c710: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
c720: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
c730: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
c740: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
c750: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
c760: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
c770: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
c780: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
c790: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
c7a0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
c7b0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
c7c0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
c7d0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
c7e0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
c7f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
c800: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
c810: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
c820: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
c830: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
c840: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
c850: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
c860: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
c870: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
c880: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
c890: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
c8a0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
c8b0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
c8c0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
c8d0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
c8e0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
c8f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
c900: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
c910: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
c920: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c930: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
c940: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
c950: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
c960: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
c970: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c980: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
c990: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
c9a0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
c9b0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
c9c0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
c9d0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
c9e0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
c9f0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
ca00: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
ca10: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
ca20: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
ca30: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
ca40: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
ca50: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
ca60: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
ca70: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
ca80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ca90: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
caa0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
cab0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
cac0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
cad0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
cae0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
caf0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
cb00: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
cb10: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
cb20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cb30: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
cb40: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
cb50: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
cb60: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
cb70: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
cb80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cb90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cba0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
cbb0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
cbc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cbd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cbe0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
cbf0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
cc00: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
cc10: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
cc20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
cc30: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
cc40: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
cc50: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
cc60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cc70: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
cc80: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
cc90: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
cca0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
ccb0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
ccc0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
ccd0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
cce0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
ccf0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
cd00: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
cd10: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
cd20: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
cd30: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
cd40: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
cd50: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
cd60: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
cd70: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
cd80: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
cd90: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
cda0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
cdb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
cdc0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
cdd0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
cde0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
cdf0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
ce00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ce10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ce20: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
ce30: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ce40: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
ce50: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
ce60: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
ce70: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
ce80: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
ce90: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
cea0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
ceb0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
cec0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
ced0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
cee0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
cef0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
cf00: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cf10: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
cf20: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
cf30: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
cf40: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
cf50: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
cf60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cf70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cf80: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
cf90: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
cfa0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
cfb0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
cfc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
cfd0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
cfe0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
cff0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
d000: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d010: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d020: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
d030: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
d040: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
d050: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
d060: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d070: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
d080: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d090: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
d0a0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
d0b0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
d0c0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
d0d0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
d0e0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
d0f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d100: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d110: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
d120: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
d130: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d140: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
d150: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
d160: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
d170: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
d180: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
d190: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
d1a0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
d1b0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
d1c0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
d1d0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
d1e0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
d1f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d200: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
d210: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
d220: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
d230: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
d240: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
d250: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d260: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
d270: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d280: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
d290: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
d2a0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
d2b0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
d2c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d2d0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
d2e0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
d2f0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
d300: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
d310: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
d320: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d330: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
d340: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
d350: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
d360: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
d370: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
d380: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
d390: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
d3a0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
d3b0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
d3c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d3d0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
d3e0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d3f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
d400: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
d410: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
d420: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
d430: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
d440: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
d450: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
d460: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
d470: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
d480: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
d490: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d4a0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
d4d0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
d4e0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
d4f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
d500: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d510: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
d520: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
d530: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
d540: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
d550: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d560: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d570: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
d580: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
d590: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
d5a0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
d5b0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
d5c0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
d5d0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
d5e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
d5f0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
d600: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
d610: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
d620: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
d630: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d640: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
d650: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
d660: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
d670: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d680: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
d690: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
d6a0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
d6b0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
d6c0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
d6d0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d6e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
d6f0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
d700: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
d710: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
d720: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
d730: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
d740: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
d750: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
d760: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
d770: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
d780: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d790: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
d7a0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
d7b0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
d7c0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
d7d0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
d7e0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
d7f0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
d800: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
d810: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
d830: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
d840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
d850: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
d860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
d870: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
d880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d890: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
d8a0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
d8b0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
d8c0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
d8d0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
d8e0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
d8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
d900: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
d910: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
d920: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
d930: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
d940: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
d950: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
d960: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
d970: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
d980: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
d990: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
d9a0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
d9b0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
d9c0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
d9d0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
d9e0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
d9f0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
da00: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
da10: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
da20: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
da30: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
da40: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
da50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
da60: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
da70: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
da80: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
da90: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
daa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
dab0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
dac0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
dad0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
dae0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
daf0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
db00: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
db10: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
db20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
db30: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
db40: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
db50: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
db60: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
db70: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
db80: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
db90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
dba0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
dbb0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
dbc0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
dbd0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dbe0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
dbf0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
dc00: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
dc10: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
dc20: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
dc30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dc40: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
dc50: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
dc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
dc70: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
dc80: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
dc90: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
dca0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dcb0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
dcc0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
dcd0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
dce0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
dcf0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
dd00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
dd10: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
dd20: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
dd30: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
dd40: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
dd50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
dd60: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
dd70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dd80: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
dd90: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
dda0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ddb0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ddc0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ddd0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
dde0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ddf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
de00: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
de10: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
de20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
de30: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
de40: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
de50: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
de60: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
de70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
de80: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
de90: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
dea0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
deb0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
dec0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
ded0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dee0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
def0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
df00: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
df10: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
df20: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
df30: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
df40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
df50: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
df60: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
df70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
df80: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
df90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dfa0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
dfb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dfc0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
dfd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
dfe0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
dff0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e000: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
e010: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
e020: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
e030: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
e040: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
e050: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
e060: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
e070: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
e080: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
e090: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
e0a0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
e0b0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
e0c0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
e0d0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
e0e0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
e0f0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
e100: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
e110: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
e120: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
e130: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
e140: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
e150: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
e160: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
e170: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
e180: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
e190: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
e1a0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e1b0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
e1c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
e1d0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
e1e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e1f0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
e200: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
e210: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
e220: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
e230: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e240: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
e250: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
e260: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
e270: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
e280: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e290: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
e2a0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e2b0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
e2c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
e2d0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
e2e0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
e2f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
e300: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
e310: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e320: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
e330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e340: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
e350: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
e360: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
e370: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
e380: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
e390: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
e3a0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
e3b0: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
e3c0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e3d0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
e3e0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
e3f0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e400: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e410: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
e420: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
e430: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
e440: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
e450: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
e460: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
e470: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
e480: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
e490: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
e4a0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
e4b0: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
e4c0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
e4d0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
e4e0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
e4f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
e500: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
e510: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
e520: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
e530: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
e540: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
e550: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
e560: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
e570: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
e580: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
e590: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
e5a0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
e5b0: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
e5c0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
e5d0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
e5e0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
e5f0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
e600: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
e610: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
e620: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
e630: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
e640: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
e650: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
e660: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
e670: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
e680: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e690: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
e6a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e6b0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
e6c0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
e6d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
e6e0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
e6f0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
e700: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e710: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
e720: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
e730: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
e740: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e750: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
e760: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
e770: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
e780: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
e790: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
e7a0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
e7b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
e7c0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
e7d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e7e0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
e7f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
e800: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
e810: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
e820: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
e830: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
e840: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
e850: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
e860: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
e870: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
e880: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
e890: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
e8a0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
e8b0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
e8c0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
e8d0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
e8e0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
e8f0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
e900: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
e910: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
e920: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e930: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e940: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
e950: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
e960: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e970: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
e980: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
e990: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
e9a0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
e9b0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
e9c0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
e9d0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
e9e0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
e9f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
ea00: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
ea10: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
ea20: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
ea30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
ea40: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
ea50: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
ea60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea70: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
ea80: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ea90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
eaa0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
eab0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
eac0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
ead0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
eae0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
eaf0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
eb00: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
eb10: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
eb20: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
eb30: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
eb40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
eb50: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
eb60: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
eb70: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
eb80: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
eb90: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
eba0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
ebb0: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
ebc0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
ebd0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
ebe0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
ebf0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ec00: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ec10: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
ec20: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ec30: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
ec40: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
ec50: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
ec60: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
ec70: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
ec80: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
ec90: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
eca0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
ecb0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
ecc0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
ecd0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
ece0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
ecf0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
ed00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
ed10: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
ed20: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
ed30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ed40: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
ed50: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
ed60: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
ed70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed80: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
ed90: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
eda0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
edb0: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
edc0: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
edd0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ede0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
edf0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ee00: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ee10: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ee20: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ee30: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ee40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ee50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ee60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ee70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ee80: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ee90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
eea0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
eeb0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
eec0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
eed0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
eee0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
eef0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
ef00: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
ef10: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
ef20: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
ef30: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ef40: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
ef50: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
ef60: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
ef70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ef80: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
ef90: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
efa0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
efb0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
efc0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
efd0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
efe0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
eff0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
f000: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
f010: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
f020: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
f030: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f040: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
f050: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f070: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
f080: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f090: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
f0a0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
f0b0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
f0c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
f0d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
f0e0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
f0f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f100: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
f110: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
f120: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
f130: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f140: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
f150: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f160: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
f170: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f180: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
f190: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
f1a0: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
f1b0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
f1c0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
f1d0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
f1e0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
f1f0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
f200: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
f210: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
f220: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
f230: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
f240: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
f250: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
f260: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
f270: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
f280: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
f290: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
f2a0: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
f2b0: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
f2c0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
f2d0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
f2e0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
f2f0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f300: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
f310: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
f320: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
f330: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
f340: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
f350: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
f360: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
f370: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
f380: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
f390: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
f3a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f3b0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f3c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
f3d0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
f3e0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
f3f0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
f400: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
f410: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f420: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
f430: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
f440: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f450: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
f460: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f470: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
f480: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
f490: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f4a0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
f4b0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
f4c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
f4d0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
f4e0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
f4f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
f500: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f510: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
f520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
f530: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
f540: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
f550: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
f560: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
f570: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
f580: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
f590: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
f5a0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
f5b0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
f5c0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
f5d0: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
f5e0: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
f5f0: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
f600: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
f610: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
f620: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
f630: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
f640: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
f650: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
f660: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
f670: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
f680: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
f690: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
f6a0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
f6b0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
f6c0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
f6d0: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
f6e0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
f6f0: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
f700: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
f710: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
f720: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f730: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
f740: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
f750: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
f760: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
f770: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
f780: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
f790: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
f7a0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
f7b0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
f7c0: 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
f7d0: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
f7e0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
f7f0: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
f800: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
f810: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
f820: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
f830: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
f840: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
f850: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
f860: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
f870: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
f880: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
f890: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
f8a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
f8b0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
f8c0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
f8d0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
f8e0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
f8f0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
f900: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
f910: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
f920: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
f930: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
f940: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
f950: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
f960: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
f970: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
f980: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
f990: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
f9a0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
f9b0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
f9c0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
f9d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
f9e0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
f9f0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
fa00: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
fa10: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
fa20: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
fa30: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
fa40: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
fa50: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
fa60: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
fa70: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
fa80: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
fa90: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
faa0: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
fab0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
fac0: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
fad0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
fae0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
faf0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
fb00: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
fb10: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
fb20: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
fb30: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
fb40: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
fb50: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
fb60: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
fb70: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
fb80: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
fb90: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
fba0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
fbb0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
fbc0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
fbd0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
fbe0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
fbf0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
fc00: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
fc10: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
fc20: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
fc30: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
fc40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fc50: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
fc60: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
fc70: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
fc80: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
fc90: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
fca0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
fcb0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
fcc0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
fcd0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
fce0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
fcf0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
fd00: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
fd10: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
fd20: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
fd30: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
fd40: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
fd50: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
fd60: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
fd70: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
fd80: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
fd90: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
fda0: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
fdb0: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
fdc0: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
fdd0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
fde0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
fdf0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
fe00: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
fe10: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
fe20: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
fe30: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
fe40: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
fe50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fe60: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
fe70: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
fe80: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
fe90: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
fea0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
feb0: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
fec0: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
fed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
fee0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
fef0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
ff00: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
ff10: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
ff20: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
ff30: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
ff40: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
ff50: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
ff60: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
ff70: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
ff80: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
ff90: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
ffa0: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
ffb0: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
ffc0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
ffd0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
ffe0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
fff0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
10000 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10010 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
10020 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
10030 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
10040 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
10050 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
10060 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
10070 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
10080 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
10090 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
100a0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
100b0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
100c0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
100d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
100e0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
100f0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
10100 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
10110 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10120 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
10130 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
10140 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
10150 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
10160 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
10170 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
10180 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
10190 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
101a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
101b0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
101c0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
101d0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
101e0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
101f0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10200 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
10220 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
10230 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
10240 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
10250 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10260 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
10270 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
10280 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
10290 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
102a0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
102b0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
102c0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
102d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
102e0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
102f0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
10300 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
10310 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10320 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
10330 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
10340 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
10350 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
10360 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
10370 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
10380 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
10390 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
103a0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
103b0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
103c0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
103d0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
103e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
103f0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
10400 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
10410 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
10420 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10430 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10440 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10450 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10460 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10470 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
10480 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
10490 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
104a0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
104b0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
104c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
104d0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
104e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
104f0 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
10500 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10510 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
10520 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
10530 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
10540 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
10550 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
10560 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
10570 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
10580 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
10590 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
105a0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
105b0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
105c0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
105d0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
105e0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
105f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10600 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10610 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10620 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10630 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10640 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10650 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10660 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
10670 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
10680 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
10690 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
106a0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
106b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
106c0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
106d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
106e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
106f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
10700 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
10710 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
10720 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
10730 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10740 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10750 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10760 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10770 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
10780 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
10790 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
107a0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
107b0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
107c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
107d0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
107e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
107f0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
10800 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
10810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10820 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
10830 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
10840 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
10850 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
10860 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
10870 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
10880 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10890 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
108a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
108b0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
108c0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
108d0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
108e0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
108f0 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
10900 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
10910 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
10920 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
10930 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
10940 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
10950 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10960 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
10970 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
10980 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10990 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
109a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
109b0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
109c0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
109d0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
109e0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
109f0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
10a00 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
10a10 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
10a20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
10a30 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10a40 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10a50 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
10a60 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
10a70 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10a80 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
10a90 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
10aa0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10ab0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
10ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10ad0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
10ae0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
10af0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
10b00 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10b10 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
10b20 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
10b30 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
10b40 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
10b50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
10b60 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
10b70 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
10b80 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
10b90 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
10ba0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
10bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
10bc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10bd0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
10be0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
10bf0 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
10c00 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
10c10 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
10c30 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
10c40 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10c50 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
10c60 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
10c70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10c80 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
10c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
10ca0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
10cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
10cc0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
10cd0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
10ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
10cf0 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
10d00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
10d10 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
10d20 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
10d30 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
10d40 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10d50 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10d60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10d70 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10d80 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10d90 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10da0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10db0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10dc0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
10dd0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
10de0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10df0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10e00 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
10e10 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10e20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
10e30 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
10e40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10e50 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10e60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10e70 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
10e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10e90 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
10ea0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
10eb0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
10ec0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
10ed0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
10ee0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
10ef0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
10f00 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10f10 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
10f20 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
10f30 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
10f40 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
10f50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
10f60 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
10f70 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
10f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10f90 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
10fa0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
10fb0 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
10fc0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
10fd0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
10fe0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
10ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
11000 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
11010 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
11020 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
11030 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
11040 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11050 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
11060 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11070 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
11080 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11090 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
110a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
110b0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
110c0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
110d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
110e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
110f0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11100 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11110 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
11120 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
11130 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
11140 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
11150 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11160 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11170 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11180 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11190 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
111a0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
111b0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
111c0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
111d0 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
111e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
111f0 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
11200 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
11210 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
11220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11230 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
11240 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11250 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
11260 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11270 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
11280 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
11290 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
112a0 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
112b0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
112c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
112d0 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
112e0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
112f0 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
11300 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
11310 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11320 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
11330 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
11340 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
11350 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
11360 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
11370 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
11380 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11390 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
113a0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
113b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
113c0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
113d0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
113e0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
113f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11400 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
11410 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
11420 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11430 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
11440 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11450 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
11460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
11470 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
11480 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
11490 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
114a0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
114b0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
114c0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
114d0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
114e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
114f0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
11500 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11510 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
11520 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11530 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11540 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
11550 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
11560 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
11570 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
11580 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11590 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
115a0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
115b0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
115c0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
115d0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
115e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
115f0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
11600 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
11610 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
11620 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
11630 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
11640 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
11650 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
11660 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
11670 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
11680 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
11690 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
116a0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
116b0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
116c0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
116d0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
116e0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
116f0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
11700 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
11710 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
11720 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
11730 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
11740 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
11750 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
11760 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
11770 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
11780 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
11790 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
117a0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
117b0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
117c0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
117d0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
117e0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
117f0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
11800 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
11810 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
11820 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
11830 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
11840 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
11850 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
11860 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
11870 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
11880 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
11890 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
118a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
118b0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
118c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
118d0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
118e0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
118f0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
11900 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
11910 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
11920 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
11930 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
11940 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
11950 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
11960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
11970 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
11980 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
11990 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
119a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
119b0 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
119c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
119d0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
119e0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
119f0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
11a00 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
11a10 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
11a20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
11a30 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
11a40 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
11a50 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
11a60 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
11a70 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
11a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
11a90 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
11aa0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
11ab0 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
11ac0 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
11ad0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
11ae0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
11af0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
11b00 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
11b10 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
11b20 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
11b30 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
11b40 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
11b50 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
11b60 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
11b70 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
11b80 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
11b90 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
11ba0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
11bb0 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
11bc0 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
11bd0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
11be0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
11bf0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
11c00 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
11c10 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11c20 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11c30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
11c40 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
11c50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
11c60 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
11c70 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
11c80 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
11c90 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
11ca0 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
11cb0 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
11cc0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
11cd0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
11ce0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
11cf0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
11d00 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
11d10 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
11d20 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
11d30 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
11d40 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
11d50 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
11d60 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
11d70 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11d80 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
11d90 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
11da0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
11db0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
11dc0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
11dd0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
11de0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11df0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
11e00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11e10 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
11e20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
11e30 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11e40 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11e50 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
11e60 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
11e70 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
11e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11e90 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
11ea0 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
11eb0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
11ec0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
11ed0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
11ee0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
11ef0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11f00 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
11f10 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
11f20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
11f30 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
11f40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
11f50 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
11f60 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
11f70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
11f80 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
11f90 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
11fa0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
11fb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
11fc0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
11fd0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
11fe0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
11ff0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
12000 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
12010 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
12020 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
12030 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
12040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12050 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
12060 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
12070 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
12080 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
12090 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
120a0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
120b0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
120c0 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
120d0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
120e0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
120f0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
12100 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
12110 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
12120 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12130 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
12140 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
12150 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
12160 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
12170 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
12180 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12190 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
121a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
121b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
121c0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
121d0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
121e0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
121f0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
12200 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
12210 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12220 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
12230 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
12240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12250 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
12260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12270 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12280 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12290 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
122a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
122b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
122c0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
122d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
122e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
122f0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
12300 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12310 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12320 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
12330 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
12340 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
12350 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
12360 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12370 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
12380 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
12390 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
123a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
123b0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
123c0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
123d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
123e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
123f0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
12400 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12410 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12420 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12430 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12440 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12450 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12460 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12470 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12480 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12490 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
124a0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
124b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
124c0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
124d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
124e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
124f0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
12500 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12510 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
12520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12530 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
12540 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
12550 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12560 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12570 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12580 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12590 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
125a0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
125b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
125c0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
125d0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
125e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
125f0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
12600 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
12610 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
12620 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
12630 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12640 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12650 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12660 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
12670 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
12680 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12690 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
126a0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
126b0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
126c0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
126d0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
126e0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
126f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12700 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12710 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12720 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12730 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12740 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12750 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
12760 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
12770 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
12780 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
12790 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
127a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
127b0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
127c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
127d0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
127e0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
127f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
12800 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
12810 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12820 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
12830 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12840 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
12850 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12860 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
12870 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
12880 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
12890 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
128a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
128b0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
128c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
128d0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
128e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
128f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12900 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
12910 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
12920 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
12930 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
12940 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12950 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
12960 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
12970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
12980 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
12990 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
129a0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
129b0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
129c0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
129d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
129e0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
129f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
12a00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
12a10 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
12a20 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
12a30 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
12a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
12a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12a70 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
12a90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12aa0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12ab0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12ac0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
12ad0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
12ae0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
12af0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
12b00 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
12b10 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
12b20 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
12b30 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
12b40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
12b50 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
12b60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
12b70 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
12b80 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
12b90 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
12ba0 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
12bb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12bc0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
12bd0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12be0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
12bf0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12c00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12c10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12c20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12c30 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
12c40 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12c50 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
12c60 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
12c70 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
12c80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
12c90 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
12ca0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
12cb0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12cc0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
12cd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12ce0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
12cf0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
12d00 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
12d10 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12d20 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
12d30 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
12d40 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
12d50 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
12d60 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
12d70 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
12d80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
12d90 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
12da0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
12db0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
12dc0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
12dd0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
12de0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
12df0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
12e00 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
12e10 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
12e20 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
12e30 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
12e40 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
12e50 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
12e60 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
12e70 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12e80 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
12e90 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
12ea0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
12eb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12ec0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
12ed0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
12ee0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
12ef0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
12f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
12f10 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
12f20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
12f30 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
12f40 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
12f50 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
12f60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
12f70 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
12f80 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
12f90 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
12fa0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
12fb0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
12fc0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
12fd0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
12fe0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
12ff0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
13000 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
13010 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
13020 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
13030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13040 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
13050 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
13060 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
13070 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
13080 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
13090 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
130a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
130b0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
130c0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
130d0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
130e0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
130f0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
13100 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
13110 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
13120 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
13130 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
13150 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13160 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
13170 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
13180 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13190 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
131a0 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  . If non-zero, t
131b0 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c  hen.** URI handl
131c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
131d0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
131e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
131f0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
13200 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61  ling.** is globa
13210 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66  lly disabled. If
13220 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13230 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
13240 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
13250 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
13260 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
13270 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
13280 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
13290 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
132a0 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
132b0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
132c0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
132d0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
132e0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
132f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
13300 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
13310 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
13320 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
13330 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
13340 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74  is opened. If it
13350 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13360 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
13370 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
13380 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
13390 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
133a0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
133b0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
133c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133d0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42  ion is opened. B
133e0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
133f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13400 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
13410 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
13420 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
13430 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
13440 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
13450 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
13460 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
13470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13480 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
13490 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
134a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
134b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
134c0 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
134d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
134e0 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e   integer argumen
134f0 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
13500 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62  preted as.** a b
13510 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
13520 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
13530 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
13540 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
13550 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62   for.** full tab
13560 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
13570 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
13580 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 73 65    The default se
13590 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
135a0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
135b0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
135c0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
135d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
135e0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
135f0 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
13600 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13610 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
13620 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
13630 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
13640 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
13650 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
13660 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
13670 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
13680 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
13690 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
136a0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
136b0 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  n.** malfunction
136c0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
136d0 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
136e0 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
136f0 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
13700 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
13710 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
13720 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
13730 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
13740 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
13750 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
13760 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
13770 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
13780 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13790 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
137a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
137b0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
137c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
137d0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
137e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
137f0 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
13800 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
13810 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
13820 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
13830 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
13840 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
13850 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
13860 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
13870 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
13880 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dl>.**.** [[
13890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
138a0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
138b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
138c0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
138d0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
138e0 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
138f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13900 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
13910 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70  _ENABLE_SQLLOG p
13920 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
13930 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
13940 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
13950 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
13960 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
13970 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
13980 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
13990 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
139a0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
139b0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
139c0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
139d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
139e0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
139f0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
13a00 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
13a10 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
13a20 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
13a30 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
13a40 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
13a50 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
13a60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
13a70 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
13a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13a90 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
13aa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13ab0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
13ac0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
13ad0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
13ae0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
13af0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
13b00 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
13b10 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
13b20 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
13b30 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
13b40 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
13b50 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
13b60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
13b70 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
13b80 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
13b90 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
13ba0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13bb0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
13bc0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
13bd0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
13be0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13bf0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
13c00 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
13c10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
13c20 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
13c30 73 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e  s case..** </dl>
13c40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13c50 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13c60 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
13c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
13c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
13c90 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
13ca0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
13cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
13cc0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
13cd0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
13ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13cf0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
13d00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
13d10 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
13d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13d30 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
13d40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
13d50 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13d60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13d70 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
13d80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
13d90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
13da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13db0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
13dc0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
13dd0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
13de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13df0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
13e00 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
13e10 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
13e20 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
13e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13e40 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
13e50 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
13e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13e70 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
13e80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
13e90 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
13ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13eb0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
13ec0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
13ed0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
13ee0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
13ef0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
13f00 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
13f10 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
13f20 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
13f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13f40 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
13f50 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
13f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13f70 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
13f80 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
13f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13fa0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
13fb0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
13fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13fd0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
13fe0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
13ff0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
14000 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14010 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
14020 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
14030 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14040 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
14050 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
14060 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
14070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14080 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14090 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
140a0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
140b0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
140d0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
140e0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
140f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14100 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
14110 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
14120 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  g, void* */../*.
14130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
14140 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
14150 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
14160 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
14170 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
14180 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
14190 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
141a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
141b0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
141c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
141d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
141e0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
141f0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
14200 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
14210 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14220 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
14230 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
14240 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
14250 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
14260 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
14270 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
14280 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
14290 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
142a0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
142b0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
142c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
142d0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
142e0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
142f0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
14300 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
14310 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
14320 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
14330 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14340 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
14350 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
14360 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
14370 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
14380 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
14390 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
143a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
143b0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
143c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
143d0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
143e0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
143f0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
14400 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
14410 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14420 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
14430 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
14440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
14450 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
14460 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
14470 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
14480 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14490 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
144a0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
144b0 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
144c0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
144d0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
144e0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
144f0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
14500 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
14510 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
14520 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
14530 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
14540 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
14550 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
14560 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
14570 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
14580 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
14590 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
145a0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
145b0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
145c0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
145d0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
145e0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
145f0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
14600 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
14610 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14620 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
14630 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
14640 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
14650 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
14660 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
14670 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
14680 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
14690 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
146a0 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
146b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
146c0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
146d0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
146e0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
146f0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
14700 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
14710 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
14720 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
14730 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
14740 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
14750 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
14760 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
14770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14780 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
14790 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
147a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
147b0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
147c0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
147d0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
147e0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
147f0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
14800 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
14810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
14820 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
14830 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14840 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
14850 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
14860 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
14870 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
14880 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
14890 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
148a0 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
148b0 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
148c0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
148d0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
148e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
148f0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
14900 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
14910 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
14920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
14930 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
14940 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14950 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
14960 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
14970 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
14980 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
14990 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
149a0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
149b0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
149c0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
149d0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
149e0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
149f0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
14a00 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
14a10 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
14a20 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
14a30 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
14a40 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
14a50 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
14a60 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
14a70 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
14a80 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
14a90 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
14aa0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
14ab0 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
14ac0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
14ad0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
14ae0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
14af0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14b00 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
14b10 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
14b20 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
14b30 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
14b40 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
14b50 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
14b60 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
14b70 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
14b80 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
14b90 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14ba0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
14bb0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
14bc0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
14bd0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
14be0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
14bf0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
14c00 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
14c10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14c20 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
14c30 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
14c40 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
14c50 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
14c60 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
14c70 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
14c80 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
14c90 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
14ca0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14cb0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
14cc0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
14cd0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
14ce0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
14cf0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
14d00 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
14d10 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
14d20 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
14d30 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
14d40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14d50 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
14d60 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
14d70 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
14d80 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
14d90 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
14da0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
14db0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
14dc0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14dd0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
14de0 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
14df0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
14e00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
14e10 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
14e20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
14e30 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
14e40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
14e50 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
14e60 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
14e70 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
14e80 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
14e90 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
14ea0 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
14eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14ec0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
14ed0 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
14ee0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14ef0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
14f00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
14f10 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
14f20 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
14f30 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
14f40 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
14f50 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
14f60 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
14f70 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
14f80 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
14f90 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
14fa0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
14fb0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
14fc0 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
14fd0 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
14fe0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
14ff0 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
15000 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
15010 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
15020 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
15030 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
15040 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
15050 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
15060 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
15070 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
15080 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
15090 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
150a0 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
150b0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
150c0 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
150d0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
150e0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
150f0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
15100 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
15110 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
15120 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
15130 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
15140 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
15150 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
15160 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
15170 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
15180 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
15190 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
151a0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
151b0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
151c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
151d0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
151e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
151f0 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c  ent.  ^As of SQL
15200 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
15210 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73  7, this routines
15220 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20  .** records the 
15230 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
15240 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61  d of both ordina
15250 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76  ry tables and [v
15260 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a  irtual tables]..
15270 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
15280 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
15290 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
152a0 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
152b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
152c0 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
152d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ed..**.** ^(If a
152e0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
152f0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
15300 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
15310 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
15320 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
15330 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
15340 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
15350 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
15360 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
15370 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
15380 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
15390 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
153a0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
153b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
153c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
153d0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
153e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
153f0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
15400 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
15410 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
15420 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
15430 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
15440 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
15450 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
15460 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
15470 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
15480 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
15490 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
154a0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
154b0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
154c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
154d0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
154e0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
154f0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
15500 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
15510 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
15520 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
15530 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
15540 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
15550 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
15560 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
15570 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
15580 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
15590 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
155a0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
155b0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
155c0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
155d0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
155e0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
155f0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
15600 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
15610 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
15620 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
15630 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
15640 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
15650 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
15660 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
15670 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
15680 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
15690 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
156a0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
156b0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
156c0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
156d0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
156e0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
156f0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
15700 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
15710 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
15720 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
15730 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
15740 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
15750 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
15760 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
15770 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
15780 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
15790 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
157a0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
157b0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
157c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
157d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
157e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
157f0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
15800 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
15810 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
15820 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
15830 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
15840 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
15850 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
15860 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
15870 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
15880 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
15890 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
158a0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
158b0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
158c0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
158d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
158e0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
158f0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
15900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15910 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
15920 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
15930 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
15940 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
15950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
15960 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
15970 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
15980 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
15990 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
159a0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
159b0 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
159c0 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
159d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
159e0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
159f0 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
15a00 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
15a10 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
15a20 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
15a30 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
15a40 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
15a50 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
15a60 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
15a70 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
15a80 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
15a90 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
15aa0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
15ab0 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
15ac0 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
15ad0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
15ae0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
15af0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
15b00 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
15b10 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
15b20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
15b30 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
15b40 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
15b50 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
15b60 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
15b70 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
15b80 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
15b90 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
15ba0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
15bb0 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
15bc0 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
15bd0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
15be0 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
15bf0 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
15c00 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
15c10 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
15c20 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
15c30 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
15c40 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
15c50 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
15c60 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
15c70 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
15c80 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
15c90 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
15ca0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
15cb0 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
15cc0 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
15cd0 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
15ce0 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
15cf0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
15d00 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
15d10 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
15d20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
15d30 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
15d40 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
15d50 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
15d60 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
15d70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
15d80 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15d90 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
15da0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
15db0 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
15dc0 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
15dd0 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
15de0 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
15df0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
15e00 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
15e10 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
15e20 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
15e30 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
15e40 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
15e50 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
15e60 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
15e70 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
15e80 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
15e90 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
15ea0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
15eb0 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
15ec0 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
15ed0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
15ee0 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
15ef0 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
15f00 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
15f10 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
15f20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
15f30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
15f40 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
15f50 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
15f60 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
15f70 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15f80 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
15f90 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
15fa0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
15fb0 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
15fc0 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
15fd0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
15fe0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
15ff0 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
16000 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
16010 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
16020 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16030 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
16040 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
16050 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
16060 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
16070 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
16080 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
16090 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
160a0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
160b0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
160c0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
160d0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
160e0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
160f0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
16100 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
16110 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
16120 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
16130 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
16140 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
16150 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
16160 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
16170 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
16180 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
16190 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
161a0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
161b0 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
161c0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
161d0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
161e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
161f0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
16200 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
16210 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
16220 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
16230 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
16240 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
16250 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
16260 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
16270 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
16280 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
16290 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
162a0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
162b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
162c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
162d0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
162e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
162f0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
16300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16310 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
16320 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
16330 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
16340 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
16350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
16360 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
16370 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
16380 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
16390 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
163a0 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
163b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
163c0 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
163d0 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
163e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
163f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
16400 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
16410 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
16420 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16430 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
16440 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
16450 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
16460 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
16470 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
16480 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
16490 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
164a0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
164b0 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
164c0 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
164d0 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
164e0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
164f0 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
16500 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
16510 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
16520 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
16530 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
16540 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
16550 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
16560 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
16570 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
16580 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
16590 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
165a0 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
165b0 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
165c0 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
165d0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
165e0 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
165f0 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
16600 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
16610 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
16620 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
16630 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
16640 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
16650 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
16660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
16670 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
16680 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
16690 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
166a0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
166b0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
166c0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
166d0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
166e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
166f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
16700 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
16710 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
16720 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
16730 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
16740 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
16750 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16760 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
16770 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
16780 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
16790 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
167a0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
167b0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
167c0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
167d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
167e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
167f0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
16800 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
16810 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16820 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
16830 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
16840 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
16850 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
16860 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
16870 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
16880 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
16890 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
168a0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
168b0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
168c0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
168d0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
168e0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
168f0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
16900 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
16910 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
16920 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
16930 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
16940 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
16950 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
16960 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
16970 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
16980 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
16990 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
169a0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
169b0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
169c0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
169d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
169e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
169f0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
16a00 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
16a10 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
16a20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16a30 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
16a40 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
16a50 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
16a60 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
16a70 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
16a80 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
16a90 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
16aa0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
16ab0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
16ac0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
16ad0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
16ae0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
16af0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
16b00 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
16b10 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
16b20 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
16b30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
16b40 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
16b50 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
16b60 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
16b70 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
16b80 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
16b90 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
16ba0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
16bb0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
16bc0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
16bd0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
16be0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
16bf0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
16c00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
16c10 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
16c20 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
16c30 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
16c40 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
16c50 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
16c60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16c70 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
16c80 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
16c90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
16ca0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
16cb0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
16cc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
16cd0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
16ce0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
16cf0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
16d00 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
16d10 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
16d20 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
16d30 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
16d40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16d50 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
16d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16d70 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
16d80 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
16d90 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
16da0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
16db0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
16dc0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
16dd0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16de0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
16df0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16e00 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
16e10 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
16e20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
16e30 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
16e40 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
16e50 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
16e60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
16e70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
16e80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
16e90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
16ea0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
16eb0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
16ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
16ed0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
16ee0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
16ef0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
16f00 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
16f10 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
16f20 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
16f30 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
16f40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16f50 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
16f60 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
16f70 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
16f80 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
16f90 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
16fa0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
16fb0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
16fc0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
16fd0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
16fe0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
16ff0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
17000 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
17010 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
17020 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
17030 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
17040 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
17050 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
17060 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
17070 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
17080 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
17090 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
170a0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
170b0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
170c0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
170d0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
170e0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
170f0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
17100 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
17110 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
17120 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
17130 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
17140 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
17150 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
17160 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
17170 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
17180 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
17190 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
171a0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
171b0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
171c0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
171d0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
171e0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
171f0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
17200 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
17210 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
17220 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
17230 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
17240 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
17250 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
17260 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
17270 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
17280 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
17290 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
172a0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
172b0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
172c0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
172d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
172e0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
172f0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
17300 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
17310 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
17320 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
17330 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
17340 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
17350 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
17360 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
17370 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
17380 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
17390 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
173a0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
173b0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
173c0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
173d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
173e0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
173f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
17400 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
17410 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
17420 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
17430 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
17440 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
17450 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
17460 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
17470 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
17480 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
17490 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
174a0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
174b0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
174c0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
174d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
174e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
174f0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
17500 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
17510 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
17520 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
17530 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
17540 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
17550 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
17560 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
17570 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
17580 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
17590 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
175a0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
175b0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
175c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
175d0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
175e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
175f0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
17600 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
17610 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
17620 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
17630 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
17640 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17650 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
17660 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
17670 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
17680 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
17690 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
176a0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
176b0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
176c0 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
176d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
176e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
176f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
17700 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17710 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
17720 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
17730 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
17740 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
17750 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
17760 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
17770 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
17780 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17790 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
177a0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
177b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
177c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
177d0 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
177e0 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
177f0 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
17800 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
17810 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17820 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
17830 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
17840 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17850 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
17860 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
17870 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
17880 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
17890 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
178a0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
178b0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
178c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
178d0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
178e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
178f0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
17900 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
17910 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
17920 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
17930 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
17940 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17950 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
17960 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
17970 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17980 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
17990 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
179a0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
179b0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
179c0 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
179d0 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
179e0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
179f0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
17a00 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
17a10 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
17a20 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
17a30 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
17a40 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
17a50 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
17a60 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
17a70 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
17a80 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
17a90 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
17aa0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
17ab0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
17ac0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
17ad0 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
17ae0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17af0 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
17b00 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
17b10 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
17b20 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
17b30 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
17b40 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
17b50 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
17b60 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
17b70 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
17b80 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
17b90 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
17ba0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
17bb0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
17bc0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
17bd0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
17be0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
17bf0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
17c00 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
17c10 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
17c20 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
17c30 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
17c40 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
17c50 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
17c60 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
17c70 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
17c80 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
17c90 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
17ca0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
17cb0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
17cc0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
17cd0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
17ce0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
17cf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17d00 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
17d10 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
17d20 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
17d30 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
17d40 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
17d50 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
17d60 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
17d70 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
17d80 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
17d90 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
17da0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
17db0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
17dc0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
17dd0 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
17de0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
17df0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
17e00 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
17e10 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
17e20 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
17e30 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
17e40 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
17e50 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
17e60 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
17e70 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
17e80 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
17e90 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
17ea0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
17eb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
17ec0 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
17ed0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
17ee0 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
17ef0 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
17f00 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
17f10 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
17f20 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
17f30 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
17f40 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
17f50 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
17f60 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
17f70 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
17f80 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
17f90 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
17fa0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
17fb0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
17fc0 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
17fd0 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
17fe0 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
17ff0 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
18000 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
18010 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
18020 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18030 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
18040 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
18050 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
18060 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
18070 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
18080 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
18090 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
180a0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
180b0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
180c0 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
180d0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
180e0 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
180f0 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
18100 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
18110 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
18120 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
18130 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
18140 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
18150 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
18160 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
18170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
18180 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
18190 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
181a0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
181b0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
181c0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
181d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
181e0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
181f0 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
18200 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
18210 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
18220 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
18230 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
18240 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
18250 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
18260 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
18270 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
18280 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
18290 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
182a0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
182b0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
182c0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
182d0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
182e0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
182f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18300 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
18310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
18320 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
18330 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18340 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18350 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
18360 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
18370 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
18380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18390 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
183a0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
183b0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
183c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
183d0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
183e0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
183f0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
18400 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
18410 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
18420 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
18430 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
18440 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
18450 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
18460 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
18470 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
18480 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
18490 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
184a0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
184b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
184c0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
184d0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
184e0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
184f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18500 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
18510 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18520 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18530 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
18540 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
18550 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
18560 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
18570 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
18580 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
18590 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
185a0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
185b0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
185c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
185d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
185e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
185f0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
18600 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
18610 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
18620 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
18630 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
18640 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
18650 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
18660 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
18670 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
18680 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
18690 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
186a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
186b0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
186c0 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
186d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
186e0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
186f0 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
18700 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
18710 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
18720 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
18730 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
18740 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
18750 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
18760 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
18770 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
18780 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
18790 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
187a0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
187b0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
187c0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
187d0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
187e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
187f0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
18800 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
18810 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
18820 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
18830 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
18840 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
18850 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
18860 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
18870 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
18880 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
18890 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
188a0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
188b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
188c0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
188d0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
188e0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
188f0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
18900 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
18910 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
18920 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
18930 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
18940 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
18950 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
18960 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
18970 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
18980 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
18990 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
189a0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
189b0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
189c0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
189d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
189e0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
189f0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
18a00 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
18a10 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
18a20 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
18a30 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
18a40 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
18a50 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
18a60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
18a70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
18a80 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
18a90 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
18aa0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
18ab0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
18ac0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
18ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
18ae0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
18af0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
18b00 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
18b10 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
18b20 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
18b30 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
18b40 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
18b50 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
18b60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18b70 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
18b80 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
18b90 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
18ba0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
18bb0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
18bc0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
18bd0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18be0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
18bf0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
18c00 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
18c10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
18c20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
18c30 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
18c40 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
18c50 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
18c60 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
18c70 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
18c80 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
18c90 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
18ca0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
18cb0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
18cc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
18cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
18ce0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
18cf0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
18d00 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
18d10 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
18d20 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
18d30 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
18d40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
18d50 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
18d60 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
18d70 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
18d80 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
18d90 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
18da0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
18db0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18dc0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
18dd0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
18de0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
18df0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
18e00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
18e10 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
18e20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18e30 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
18e40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18e50 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
18e60 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18e70 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
18e80 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
18e90 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
18ea0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
18eb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18ec0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
18ed0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
18ee0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
18ef0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18f00 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
18f10 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
18f20 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
18f30 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
18f40 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
18f50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
18f60 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
18f70 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
18f80 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
18f90 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
18fa0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
18fb0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
18fc0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
18fd0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
18fe0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
18ff0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
19000 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
19010 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
19020 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
19030 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19040 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
19050 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19060 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
19070 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
19080 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
19090 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
190a0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
190b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
190c0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
190d0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
190e0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
190f0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
19100 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
19110 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
19120 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
19130 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
19140 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
19150 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
19160 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
19170 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
19180 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
19190 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
191a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
191b0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
191c0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
191d0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
191e0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
191f0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
19200 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
19210 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
19220 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
19230 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
19240 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
19250 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
19260 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
19270 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
19280 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
19290 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
192a0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
192b0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
192c0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
192d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
192e0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
192f0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
19300 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
19310 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
19320 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
19330 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
19340 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
19350 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
19360 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
19370 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
19380 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
19390 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
193a0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
193b0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
193c0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
193d0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
193e0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
193f0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
19400 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
19410 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
19420 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
19430 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
19440 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
19450 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
19460 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
19470 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
19480 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
19490 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
194a0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
194b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
194c0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
194d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
194e0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
194f0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
19500 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
19510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
19520 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
19530 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
19540 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
19550 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
19560 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
19570 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
19580 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
19590 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
195a0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
195b0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
195c0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
195d0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
195e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
195f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
19600 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
19610 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
19620 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
19630 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
19640 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
19650 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
19660 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
19670 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
19680 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
19690 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
196a0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
196b0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
196c0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
196d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
196e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
196f0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
19700 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
19710 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
19720 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
19730 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
19740 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
19750 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
19760 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
19770 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
19780 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
19790 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
197a0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
197b0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
197c0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
197d0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
197e0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
197f0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
19800 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
19810 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
19820 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
19830 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
19840 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
19850 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19860 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
19870 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
19880 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
19890 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
198a0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
198b0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
198c0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
198d0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
198e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
198f0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
19900 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
19910 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
19920 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
19930 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
19940 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
19950 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
19960 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
19970 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
19980 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
19990 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
199a0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
199b0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
199c0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
199d0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
199e0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
199f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
19a00 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
19a10 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
19a20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
19a30 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
19a40 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
19a50 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
19a60 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
19a70 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
19a80 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
19a90 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
19aa0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
19ab0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
19ac0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
19ad0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
19ae0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
19af0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
19b00 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
19b10 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
19b20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
19b30 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
19b40 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
19b50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
19b60 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
19b70 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
19b80 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
19b90 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
19ba0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
19bb0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
19bc0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
19bd0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
19be0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
19bf0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
19c00 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
19c10 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
19c20 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
19c30 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
19c40 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
19c50 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
19c60 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
19c70 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
19c80 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
19c90 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
19ca0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
19cb0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
19cc0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
19cd0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
19ce0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
19cf0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
19d00 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
19d10 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
19d20 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
19d30 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
19d40 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
19d50 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
19d60 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
19d70 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
19d80 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
19d90 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
19da0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
19db0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
19dc0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
19dd0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
19de0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
19df0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
19e00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19e10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
19e20 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
19e30 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
19e40 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
19e50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
19e60 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
19e70 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
19e80 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
19e90 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
19ea0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
19eb0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
19ec0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
19ed0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
19ee0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
19ef0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
19f00 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19f10 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
19f20 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
19f30 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
19f40 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
19f50 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
19f60 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
19f70 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
19f80 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
19f90 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19fa0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
19fb0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
19fc0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
19fd0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19fe0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19ff0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1a000 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1a010 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1a020 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1a030 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1a040 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1a050 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a060 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1a070 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1a080 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1a090 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1a0a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a0b0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1a0c0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1a0d0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1a0e0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1a0f0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1a100 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1a110 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1a120 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1a130 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1a140 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1a150 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1a160 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1a170 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1a180 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1a190 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1a1a0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1a1b0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1a1c0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1a1d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1a1e0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1a1f0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1a200 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1a210 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1a220 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1a230 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1a240 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1a250 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1a260 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1a270 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a280 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1a290 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1a2a0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1a2b0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1a2c0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1a2d0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1a2e0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1a2f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1a300 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1a310 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a320 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1a330 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1a340 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1a350 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1a360 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1a370 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1a380 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1a390 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1a3a0 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1a3b0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1a3c0 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1a3d0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1a3e0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1a3f0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1a400 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1a410 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1a420 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1a430 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1a440 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1a450 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
1a460 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1a470 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1a480 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
1a490 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1a4a0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1a4b0 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
1a4c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1a4d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1a4e0 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
1a4f0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1a500 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1a510 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1a520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a530 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1a540 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1a550 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1a560 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1a570 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1a580 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1a590 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1a5a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1a5b0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1a5c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1a5d0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1a5e0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1a5f0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1a600 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1a610 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1a620 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1a630 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1a640 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1a650 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1a660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1a670 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1a680 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1a690 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1a6a0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1a6b0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1a6c0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1a6d0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1a6e0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1a6f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1a700 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1a710 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1a720 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1a730 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1a740 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1a750 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1a760 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1a770 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1a780 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1a790 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1a7a0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1a7b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1a7c0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1a7d0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1a7e0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1a7f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1a800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a810 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1a820 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1a830 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1a840 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1a850 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1a860 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1a870 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1a880 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1a890 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1a8a0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1a8b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1a8c0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1a8d0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1a8e0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1a8f0 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1a900 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1a910 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1a920 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1a930 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1a940 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1a950 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1a960 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1a970 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1a980 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1a990 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1a9a0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1a9b0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1a9c0 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1a9d0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1a9e0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1a9f0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1aa00 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1aa10 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1aa20 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1aa30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1aa40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1aa50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1aa60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1aa70 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1aa80 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1aa90 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1aaa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1aab0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1aac0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1aad0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1aae0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1aaf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1ab00 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1ab10 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1ab20 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1ab30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ab40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ab50 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1ab60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1ab70 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1ab80 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1ab90 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1aba0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1abb0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1abc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1abd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1abe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1abf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1ac00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ac10 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1ac20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1ac30 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1ac40 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1ac50 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1ac60 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1ac70 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1ac80 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1ac90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1aca0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1acb0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1acc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1acd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ace0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1acf0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1ad00 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1ad10 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1ad20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1ad30 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1ad40 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1ad50 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1ad60 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1ad70 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1ad80 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1ad90 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1ada0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1adb0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1adc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1add0 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1ade0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1adf0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1ae00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ae10 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1ae20 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1ae30 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1ae40 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1ae50 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1ae60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1ae70 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1ae80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1ae90 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1aea0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1aeb0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1aec0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1aed0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1aee0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1aef0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1af00 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1af10 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1af20 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1af30 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1af40 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1af50 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1af60 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1af70 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1af80 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1af90 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1afa0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1afb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1afc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1afd0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1afe0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1aff0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1b000 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1b010 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1b020 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1b030 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1b040 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1b050 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1b060 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1b070 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1b080 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1b090 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b0a0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1b0b0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1b0c0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1b0d0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1b0e0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1b0f0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1b100 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1b110 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1b120 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1b130 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1b140 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1b150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1b160 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1b170 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1b180 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1b190 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1b1a0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1b1b0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1b1c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1b1d0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1b1e0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1b1f0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1b200 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1b210 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1b220 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1b230 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1b240 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1b250 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1b260 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1b270 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b280 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1b290 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1b2a0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1b2b0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1b2c0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1b2d0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1b2e0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1b2f0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1b300 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1b310 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1b320 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1b330 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1b340 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1b350 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1b360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1b370 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1b380 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1b390 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
1b3a0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1b3b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b3c0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1b3d0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1b3e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1b3f0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1b400 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1b410 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1b420 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1b430 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b440 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1b450 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1b460 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1b470 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1b480 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1b490 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1b4a0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1b4b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1b4c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1b4d0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1b4e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1b4f0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1b500 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1b510 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1b520 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1b530 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1b540 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1b550 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1b560 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1b570 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1b580 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1b590 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1b5a0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1b5b0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1b5c0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1b5d0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1b5e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1b5f0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1b600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1b610 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1b620 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1b630 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1b640 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1b650 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1b660 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1b670 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1b680 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1b690 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1b6a0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1b6b0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1b6c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b6d0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1b6e0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1b6f0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1b700 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1b710 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1b720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1b730 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1b740 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1b750 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1b760 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1b770 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1b780 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1b790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1b7a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1b7b0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1b7c0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1b7d0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1b7e0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1b7f0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1b800 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1b810 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1b820 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1b830 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1b840 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1b850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1b860 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1b870 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1b880 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1b890 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1b8a0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1b8b0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1b8c0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1b8d0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1b8e0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1b8f0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1b900 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1b910 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1b920 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1b930 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1b940 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1b950 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1b960 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1b970 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1b980 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1b990 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1b9a0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1b9b0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1b9c0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1b9d0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1b9e0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1b9f0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1ba00 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1ba10 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1ba20 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1ba30 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1ba40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ba50 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
1ba60 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
1ba70 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
1ba80 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
1ba90 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
1baa0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1bab0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1bac0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
1bad0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1bae0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1baf0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1bb00 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
1bb10 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
1bb20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
1bb30 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1bb40 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1bb50 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1bb60 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1bb70 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1bb80 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1bb90 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1bba0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1bbb0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1bbc0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1bbd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1bbe0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1bbf0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1bc00 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1bc10 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1bc20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1bc30 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1bc40 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1bc50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bc60 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1bc70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1bc80 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1bc90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1bca0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1bcb0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1bcc0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1bcd0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1bce0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1bcf0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1bd00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1bd10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1bd20 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1bd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1bd40 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1bd50 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1bd60 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1bd70 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1bd80 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1bd90 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1bda0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1bdb0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1bdc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1bdd0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1bde0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1bdf0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1be00 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1be10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1be20 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1be30 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1be40 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1be50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1be60 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1be70 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1be80 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1be90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1bea0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1beb0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1bec0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1bed0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1bee0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bef0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1bf00 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1bf10 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1bf20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1bf30 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1bf40 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1bf50 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1bf60 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1bf70 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1bf80 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1bf90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bfa0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1bfb0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1bfc0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1bfd0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1bfe0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1bff0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1c000 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c010 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1c020 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1c030 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1c040 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1c050 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1c060 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1c070 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1c080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c090 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1c0a0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1c0b0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1c0c0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1c0d0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1c0e0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1c0f0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1c100 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1c110 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1c120 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1c130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1c140 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1c150 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1c160 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1c170 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1c180 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1c190 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1c1a0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1c1b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1c1c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1c1d0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1c1e0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1c1f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1c200 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1c210 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1c220 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1c230 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1c240 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1c250 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1c260 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1c270 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1c280 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1c290 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1c2a0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1c2b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1c2c0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1c2d0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1c2e0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1c2f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c300 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1c310 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1c320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1c330 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1c340 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1c350 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1c360 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1c370 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1c380 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1c390 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1c3a0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1c3b0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1c3c0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1c3d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1c3e0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1c3f0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1c400 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1c410 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1c420 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1c430 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1c440 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1c450 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1c460 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1c470 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1c480 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1c490 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1c4a0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1c4b0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1c4c0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1c4d0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1c4e0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1c4f0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1c500 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1c510 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1c520 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1c530 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1c540 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1c550 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1c560 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1c570 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1c580 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1c590 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1c5a0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1c5b0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1c5c0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1c5d0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1c5e0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1c5f0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1c600 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1c610 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1c620 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1c630 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1c640 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1c650 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1c660 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1c670 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1c680 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1c690 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1c6a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1c6b0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1c6c0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1c6d0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1c6e0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1c6f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1c700 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1c710 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1c720 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1c730 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1c740 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1c750 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c760 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1c770 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1c780 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1c790 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1c7a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1c7b0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1c7c0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1c7d0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1c7e0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1c7f0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1c800 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1c810 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1c820 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1c830 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1c840 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1c850 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1c860 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1c870 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1c880 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1c890 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1c8a0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1c8b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1c8c0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1c8d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c8e0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1c8f0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1c900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c910 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1c920 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1c930 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1c940 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1c950 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1c960 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1c970 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1c980 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1c990 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1c9a0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1c9b0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1c9c0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1c9d0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1c9e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1c9f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1ca00 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1ca10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1ca20 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1ca30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ca40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ca50 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1ca60 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1ca70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ca80 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1ca90 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1caa0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1cab0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1cac0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1cad0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1cae0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1caf0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1cb00 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1cb10 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1cb20 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1cb30 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1cb40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1cb50 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1cb60 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1cb70 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1cb80 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1cb90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1cba0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1cbb0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1cbc0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1cbd0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1cbe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1cbf0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1cc00 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1cc10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cc20 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1cc30 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1cc40 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1cc50 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1cc60 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1cc70 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1cc80 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1cc90 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1cca0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1ccb0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1ccc0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1ccd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1cce0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1ccf0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1cd00 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1cd10 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
1cd20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1cd30 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1cd40 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1cd50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1cd60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cd70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1cd80 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1cd90 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1cda0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cdb0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1cdc0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1cdd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1cde0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1cdf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ce00 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1ce10 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1ce20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1ce30 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1ce40 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1ce50 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1ce60 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1ce70 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1ce80 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1ce90 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1cea0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ceb0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1cec0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1ced0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1cee0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1cef0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1cf00 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1cf10 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1cf20 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1cf30 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1cf40 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1cf50 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1cf60 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1cf70 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1cf80 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1cf90 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1cfa0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1cfb0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1cfc0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1cfd0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1cfe0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1cff0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1d000 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1d010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1d020 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1d030 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1d040 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1d050 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1d060 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1d070 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d080 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1d090 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1d0a0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1d0b0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1d0c0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1d0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1d0e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1d0f0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1d100 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1d110 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1d120 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1d130 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1d140 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1d150 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1d160 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d170 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1d180 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1d190 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1d1a0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1d1b0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1d1c0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1d1d0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1d1e0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1d1f0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1d200 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1d210 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1d220 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1d230 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1d240 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1d250 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1d260 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1d270 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1d280 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1d290 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1d2a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d2b0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1d2c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1d2d0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1d2e0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1d2f0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1d300 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1d310 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d320 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1d330 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1d340 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1d350 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1d360 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1d370 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1d380 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1d390 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1d3a0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1d3b0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1d3c0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1d3d0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1d3e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d3f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1d400 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1d410 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1d420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d430 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1d440 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1d450 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1d460 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d480 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1d490 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1d4a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1d4b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d4c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d4d0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1d4e0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1d4f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1d500 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1d510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d520 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1d530 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1d540 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d550 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d560 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d570 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1d580 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1d590 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1d5a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d5b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1d5c0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1d5d0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1d5e0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1d5f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d600 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d610 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1d620 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1d630 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1d640 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d650 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d660 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1d670 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1d680 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d690 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d6a0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1d6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1d6c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d6d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d6e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d6f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1d700 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1d710 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1d720 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1d730 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d740 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1d750 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1d760 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d770 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d780 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d790 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1d7a0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1d7b0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1d7c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1d7d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d7e0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1d7f0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1d800 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d810 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d820 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d830 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1d840 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1d850 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1d860 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d880 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1d890 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1d8a0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1d8b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d8c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d8d0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1d8e0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1d8f0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1d900 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1d910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d920 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1d930 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1d940 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1d950 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1d970 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1d980 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1d990 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1d9a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d9b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1d9c0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1d9d0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1d9e0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1d9f0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1da00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1da10 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1da20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1da30 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1da40 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1da50 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1da60 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1da70 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1da80 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1da90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1daa0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1dab0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1dac0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1dad0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1dae0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1daf0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1db00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1db10 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1db20 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1db30 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1db40 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1db50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1db60 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1db70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1db80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1db90 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1dba0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1dbb0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1dbc0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1dbd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dbe0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1dbf0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1dc00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1dc10 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1dc20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dc30 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1dc40 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1dc50 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1dc60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1dc70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dc80 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1dc90 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1dca0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1dcb0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dcc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dcd0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1dce0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1dcf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dd00 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1dd10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dd20 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1dd30 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1dd40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dd50 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1dd60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dd70 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1dd80 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1dd90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1dda0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1ddb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ddc0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1ddd0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1dde0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1ddf0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1de00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1de10 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1de20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1de30 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1de40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1de50 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1de60 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1de70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1de80 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1de90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1dea0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1deb0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1dec0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1ded0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1dee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1def0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1df00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1df10 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1df20 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1df30 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1df40 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1df50 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1df60 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1df70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1df80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1df90 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1dfa0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1dfb0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1dfc0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1dfd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1dfe0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1dff0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1e000 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1e010 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1e020 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1e030 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1e040 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1e050 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1e060 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1e070 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1e080 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1e090 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1e0a0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1e0b0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1e0c0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1e0d0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1e0e0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1e0f0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1e100 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1e110 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1e120 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1e130 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1e140 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1e150 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1e160 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1e170 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1e180 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1e190 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1e1a0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1e1b0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1e1c0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1e1d0 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1e1e0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1e1f0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1e200 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1e210 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1e220 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1e230 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1e240 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1e250 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1e260 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1e270 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1e280 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1e290 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1e2a0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1e2b0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1e2c0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1e2d0 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1e2e0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1e2f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1e300 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1e310 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1e320 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1e330 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1e340 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1e350 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1e360 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1e370 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1e380 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1e390 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1e3a0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1e3b0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1e3c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1e3d0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1e3e0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1e3f0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1e400 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1e410 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1e420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1e430 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1e440 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1e450 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1e460 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1e470 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1e480 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1e490 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1e4a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1e4b0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1e4c0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1e4d0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1e4e0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1e4f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1e500 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1e510 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1e520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e530 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1e540 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1e550 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1e560 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1e570 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1e580 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1e590 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1e5a0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1e5b0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1e5c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e5d0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1e5e0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1e5f0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1e600 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1e610 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1e620 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1e630 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1e640 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1e650 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
1e660 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
1e670 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
1e680 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1e690 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1e6a0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1e6b0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1e6c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e6d0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1e6e0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1e6f0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1e700 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1e710 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1e720 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1e730 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1e740 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1e750 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e760 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1e770 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1e780 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1e790 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1e7a0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1e7b0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1e7c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1e7d0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1e7e0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1e7f0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1e800 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1e810 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1e820 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1e830 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1e840 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1e850 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1e860 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1e870 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1e880 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1e890 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1e8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1e8b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1e8c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1e8d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1e8e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e8f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1e900 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1e910 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1e920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e930 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1e940 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1e950 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1e960 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
1e970 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1e980 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1e990 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1e9a0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1e9b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1e9c0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1e9d0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1e9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1e9f0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1ea00 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1ea10 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1ea20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1ea30 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1ea40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1ea50 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1ea60 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1ea70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ea80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1ea90 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1eaa0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1eab0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1eac0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1ead0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1eae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eaf0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1eb00 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1eb10 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1eb20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1eb30 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1eb40 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1eb50 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1eb60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1eb70 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1eb80 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1eb90 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1eba0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1ebb0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1ebc0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1ebd0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1ebe0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1ebf0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1ec00 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1ec10 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1ec20 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1ec30 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1ec40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1ec50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1ec60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1ec70 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1ec80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1ec90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1eca0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1ecb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1ecc0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1ecd0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1ece0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1ecf0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1ed00 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1ed10 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1ed20 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1ed30 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1ed40 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1ed50 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1ed60 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1ed70 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1ed80 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1ed90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1eda0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1edb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1edc0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1edd0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1ede0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1edf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1ee00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1ee10 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1ee20 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1ee30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1ee40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1ee50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1ee60 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1ee70 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1ee80 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1ee90 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1eea0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1eeb0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1eec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1eed0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1eee0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1eef0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1ef00 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1ef10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1ef20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1ef30 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1ef40 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1ef50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1ef60 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1ef70 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1ef80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ef90 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1efa0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1efb0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1efc0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1efd0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1efe0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1eff0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1f000 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1f010 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1f020 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1f030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f040 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
1f050 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1f060 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
1f070 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1f080 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1f090 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1f0a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1f0b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f0c0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1f0d0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1f0e0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1f0f0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1f100 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1f110 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1f120 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1f130 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1f140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1f150 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1f160 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1f170 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1f180 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1f190 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1f1a0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1f1b0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1f1c0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1f1d0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1f1e0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1f1f0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1f200 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1f210 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1f220 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1f230 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1f240 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1f250 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1f260 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1f270 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1f280 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f290 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1f2a0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1f2b0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
1f2c0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1f2d0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1f2e0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1f2f0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1f300 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1f310 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1f320 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1f330 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1f340 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1f350 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f360 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1f370 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1f380 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1f390 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
1f3a0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1f3b0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
1f3c0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
1f3d0 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
1f3e0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
1f3f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1f400 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
1f410 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
1f420 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1f430 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
1f440 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f450 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
1f460 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
1f470 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
1f480 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
1f490 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
1f4a0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
1f4b0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
1f4c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1f4d0 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
1f4e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1f4f0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1f500 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
1f510 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f520 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
1f530 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
1f540 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1f550 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
1f560 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
1f570 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
1f580 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
1f590 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1f5a0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
1f5b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1f5c0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1f5d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f5e0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
1f5f0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
1f600 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1f610 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
1f620 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1f630 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
1f640 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
1f650 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1f660 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1f670 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
1f680 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1f690 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
1f6a0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1f6b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1f6c0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
1f6d0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
1f6e0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
1f6f0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
1f700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1f710 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f730 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1f740 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1f750 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1f760 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1f770 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1f780 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1f790 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1f7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1f7b0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1f7c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1f7d0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1f7e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1f7f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1f800 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1f810 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
1f820 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1f830 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1f840 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1f850 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1f860 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1f870 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1f880 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1f890 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1f8a0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1f8b0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1f8c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f8d0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1f8e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1f8f0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1f900 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1f910 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1f920 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1f930 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1f940 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1f950 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1f960 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1f970 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1f980 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1f990 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1f9a0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1f9b0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1f9c0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1f9d0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1f9e0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1f9f0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1fa00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1fa10 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1fa20 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1fa30 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1fa40 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1fa50 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1fa60 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1fa70 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1fa80 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1fa90 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1faa0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1fab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fac0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1fad0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1fae0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
1faf0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
1fb00 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
1fb10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
1fb20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
1fb30 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1fb40 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
1fb50 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1fb60 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
1fb70 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
1fb80 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
1fb90 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
1fba0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
1fbb0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1fbc0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
1fbd0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1fbe0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
1fbf0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
1fc00 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1fc10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1fc20 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
1fc30 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
1fc40 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
1fc50 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
1fc60 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
1fc70 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
1fc80 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
1fc90 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
1fca0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
1fcb0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1fcc0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
1fcd0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
1fce0 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
1fcf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1fd00 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
1fd10 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
1fd20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
1fd30 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
1fd40 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
1fd50 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
1fd60 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
1fd70 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
1fd80 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
1fd90 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1fda0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
1fdb0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
1fdc0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
1fdd0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
1fde0 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
1fdf0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
1fe00 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
1fe10 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
1fe20 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
1fe30 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
1fe40 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
1fe50 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
1fe60 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
1fe70 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
1fe80 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
1fe90 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
1fea0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
1feb0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
1fec0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
1fed0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
1fee0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
1fef0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
1ff00 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
1ff10 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
1ff20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
1ff30 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
1ff40 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
1ff50 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
1ff60 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
1ff70 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
1ff80 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
1ff90 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
1ffa0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
1ffb0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
1ffc0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
1ffd0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
1ffe0 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
1fff0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
20000 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
20010 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
20020 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
20030 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
20040 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
20050 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
20060 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
20070 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
20080 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
20090 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
200a0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
200b0 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
200c0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
200d0 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
200e0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
200f0 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
20100 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
20110 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
20120 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
20130 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
20140 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
20150 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
20160 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
20170 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
20180 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
20190 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
201a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
201b0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
201c0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
201d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
201e0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
201f0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
20200 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
20210 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
20220 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
20230 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
20240 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
20250 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
20260 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
20270 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
20280 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
20290 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
202a0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
202b0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
202c0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
202d0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
202e0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
202f0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
20300 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20310 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
20320 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
20330 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
20340 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
20350 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
20360 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
20370 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
20380 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
20390 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
203a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
203b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
203c0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
203d0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
203e0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
203f0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
20400 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
20410 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
20420 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
20430 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
20440 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
20450 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
20460 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
20470 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
20480 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
20490 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
204a0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
204b0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
204c0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
204d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
204e0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
204f0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
20500 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
20510 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
20520 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
20530 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
20540 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
20550 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
20560 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20570 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
20580 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
20590 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
205a0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
205b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
205c0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
205d0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
205e0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
205f0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
20600 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
20610 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
20620 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
20630 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
20640 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
20650 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
20660 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
20670 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
20680 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
20690 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
206a0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
206b0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
206c0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
206d0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
206e0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
206f0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
20700 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
20710 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
20720 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
20730 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
20740 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
20750 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
20760 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
20770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20780 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20790 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
207a0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
207b0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
207c0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
207d0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
207e0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
207f0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
20800 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
20810 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20820 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
20830 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20840 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
20850 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
20860 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
20870 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
20880 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
20890 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
208a0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
208b0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
208c0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
208d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
208e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
208f0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
20900 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20910 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
20920 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
20930 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
20940 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
20950 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
20960 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
20970 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
20980 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
20990 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
209a0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
209b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
209c0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
209d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
209e0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
209f0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
20a00 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
20a10 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
20a20 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
20a30 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
20a40 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
20a50 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
20a60 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
20a70 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
20a80 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
20a90 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
20aa0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
20ab0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
20ac0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
20ad0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
20ae0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20af0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
20b00 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
20b10 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
20b20 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
20b30 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
20b40 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
20b50 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
20b60 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
20b70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
20b80 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
20b90 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
20ba0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
20bb0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
20bc0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
20bd0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
20be0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20bf0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
20c00 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
20c10 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
20c20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
20c30 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
20c40 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
20c50 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
20c60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
20c70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
20c80 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20c90 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
20ca0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
20cb0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20cc0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
20cd0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
20ce0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
20cf0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
20d00 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
20d10 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
20d20 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
20d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
20d40 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
20d50 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
20d60 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
20d70 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
20d80 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
20d90 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
20da0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
20db0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
20dc0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
20dd0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
20de0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
20df0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
20e00 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
20e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
20e20 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
20e30 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
20e40 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
20e50 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
20e60 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
20e70 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
20e80 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
20e90 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
20ea0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
20eb0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
20ec0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
20ed0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
20ee0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
20ef0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
20f00 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
20f10 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
20f20 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
20f30 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
20f40 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
20f50 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
20f60 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
20f70 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
20f80 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
20f90 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
20fa0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
20fb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20fc0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
20fd0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
20fe0 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
20ff0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21000 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
21010 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
21020 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
21030 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
21040 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
21050 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
21060 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
21070 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
21080 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
21090 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
210a0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
210b0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
210c0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
210d0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
210e0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
210f0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21100 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
21110 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
21120 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
21130 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
21140 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
21150 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
21160 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
21170 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
21180 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
21190 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
211a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
211b0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
211c0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
211d0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
211e0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
211f0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21200 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
21210 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
21220 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
21230 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
21240 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
21250 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
21260 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
21270 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
21280 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
21290 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
212a0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
212b0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
212c0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
212d0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
212e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
212f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21300 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
21310 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
21320 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
21330 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
21340 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
21350 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
21360 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
21370 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
21380 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
21390 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
213a0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
213b0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
213c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
213d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
213e0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
213f0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
21400 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
21410 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
21420 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
21430 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
21440 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
21450 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21460 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
21470 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
21480 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
21490 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
214a0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
214b0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
214c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
214d0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
214e0 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
214f0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
21500 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
21510 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21520 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21530 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21540 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
21550 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
21560 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
21570 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
21580 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
21590 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
215a0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
215b0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
215c0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
215d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
215e0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
215f0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
21600 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
21610 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
21620 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21630 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21640 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21650 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
21660 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
21670 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
21680 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
21690 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
216a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
216b0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
216c0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
216d0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
216e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
216f0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
21700 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
21710 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
21720 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
21730 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
21740 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
21750 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
21760 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
21770 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
21780 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
21790 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
217a0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
217b0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
217c0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
217d0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
217e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
217f0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
21800 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
21810 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
21820 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
21830 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
21840 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
21850 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
21860 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
21870 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
21880 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
21890 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
218a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
218b0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
218c0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
218d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
218e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
218f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
21900 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
21910 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
21920 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
21930 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
21940 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
21950 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
21960 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
21970 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
21980 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
21990 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
219a0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
219b0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
219c0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
219d0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
219e0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
219f0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
21a00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
21a10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21a20 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
21a30 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
21a40 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
21a50 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
21a60 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
21a70 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
21a80 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
21a90 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
21aa0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
21ab0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
21ac0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
21ad0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
21ae0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
21af0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
21b00 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
21b10 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
21b20 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
21b30 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
21b40 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
21b50 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
21b60 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
21b70 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21b80 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
21b90 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
21ba0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
21bb0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
21bc0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
21bd0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
21be0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
21bf0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
21c00 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
21c10 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
21c20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
21c30 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
21c40 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
21c50 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
21c60 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
21c70 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
21c80 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
21c90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21ca0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
21cb0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
21cc0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
21cd0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
21ce0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
21cf0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
21d00 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
21d10 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
21d20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
21d30 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
21d40 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
21d50 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
21d60 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
21d70 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
21d80 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
21d90 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
21da0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
21db0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
21dc0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
21dd0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
21de0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
21df0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
21e00 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
21e10 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
21e20 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
21e30 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
21e40 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
21e50 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
21e60 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
21e70 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
21e80 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
21e90 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
21ea0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
21eb0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
21ec0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
21ed0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
21ee0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
21ef0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
21f00 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
21f10 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
21f20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
21f30 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
21f40 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
21f50 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
21f60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
21f70 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
21f80 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
21f90 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
21fa0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
21fb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
21fc0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
21fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21fe0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
21ff0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
22000 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
22010 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
22020 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
22030 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
22040 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
22050 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
22060 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
22070 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
22080 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
22090 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
220a0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
220b0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
220c0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
220d0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
220e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
220f0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
22100 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
22110 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
22120 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
22130 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
22140 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
22150 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
22160 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
22170 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
22180 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
22190 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
221a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
221b0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
221c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
221d0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
221e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
221f0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
22200 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
22210 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
22220 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
22230 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
22240 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
22250 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
22260 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
22270 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
22280 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
22290 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
222a0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
222b0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
222c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
222d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
222e0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
222f0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
22300 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
22310 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
22320 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
22330 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
22340 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
22350 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
22360 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
22370 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
22380 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
22390 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
223a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
223b0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
223c0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
223d0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
223e0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
223f0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
22400 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
22410 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
22420 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
22430 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
22440 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
22450 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
22460 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
22470 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
22480 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
22490 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
224a0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
224b0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
224c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
224d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
224e0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
224f0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
22500 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
22510 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
22520 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
22530 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
22540 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
22550 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
22560 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
22570 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
22580 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
22590 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
225a0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
225b0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
225c0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
225d0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
225e0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
225f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
22600 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
22610 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
22620 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
22630 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
22640 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
22650 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
22660 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
22670 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
22680 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
22690 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
226a0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
226b0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
226c0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
226d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
226e0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
226f0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
22700 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
22710 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
22720 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
22730 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
22740 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
22750 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
22760 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
22770 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
22780 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
22790 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
227a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
227b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
227c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
227d0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
227e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
227f0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
22800 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22810 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
22820 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
22830 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22840 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
22850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
22860 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
22870 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
22880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22890 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
228a0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
228b0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
228c0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
228d0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
228e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
228f0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
22900 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
22910 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
22920 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
22930 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
22940 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
22950 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
22960 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
22970 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
22980 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
22990 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
229a0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
229b0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
229c0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
229d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
229e0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
229f0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
22a00 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
22a10 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
22a20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
22a30 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
22a40 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
22a50 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
22a60 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
22a70 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
22a80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
22a90 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
22aa0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
22ab0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
22ac0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
22ad0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
22ae0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
22af0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
22b00 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
22b10 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
22b20 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
22b30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
22b40 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
22b50 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
22b60 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
22b70 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
22b80 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
22b90 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
22ba0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
22bb0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
22bc0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
22bd0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
22be0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
22bf0 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
22c00 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
22c10 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
22c20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
22c30 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
22c40 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
22c50 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
22c60 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
22c70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
22c80 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
22c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22ca0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
22cb0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
22cc0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
22cd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
22ce0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
22cf0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
22d00 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
22d10 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
22d20 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
22d30 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
22d40 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
22d50 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
22d60 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
22d70 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
22d80 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
22d90 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
22da0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
22db0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
22dc0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
22dd0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
22de0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
22df0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
22e00 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
22e10 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
22e20 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
22e30 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
22e40 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
22e50 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
22e60 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
22e70 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
22e80 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
22e90 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
22ea0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
22eb0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
22ec0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
22ed0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
22ee0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
22ef0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
22f00 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
22f10 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
22f20 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
22f30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
22f40 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
22f50 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
22f60 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
22f70 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
22f80 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
22f90 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
22fa0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
22fb0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
22fc0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
22fd0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
22fe0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
22ff0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
23000 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
23010 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
23020 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
23030 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
23040 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
23050 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
23060 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
23070 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
23080 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
23090 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
230a0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
230b0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
230c0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
230d0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
230e0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
230f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
23100 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
23110 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
23120 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
23130 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
23140 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
23150 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
23160 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
23170 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
23180 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
23190 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
231a0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
231b0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
231c0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
231d0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
231e0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
231f0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
23200 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
23210 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
23220 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
23230 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
23240 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
23250 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
23260 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
23270 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
23280 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
23290 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
232a0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
232b0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
232c0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
232d0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
232e0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
232f0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
23300 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
23310 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
23320 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
23330 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
23340 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
23350 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
23360 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
23370 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
23380 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
23390 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
233a0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
233b0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
233c0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
233d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
233e0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
233f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
23400 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
23410 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
23420 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
23430 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
23440 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
23450 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
23460 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
23470 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
23480 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
23490 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
234a0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
234b0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
234c0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
234d0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
234e0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
234f0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
23500 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
23510 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
23520 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
23530 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23540 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
23550 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
23560 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
23570 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
23580 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
23590 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
235a0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
235b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
235c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
235d0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
235e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
235f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
23600 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
23610 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
23620 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
23630 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
23640 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23650 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
23660 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
23670 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
23680 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23690 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
236a0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
236b0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
236c0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
236d0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
236e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
236f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
23700 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
23710 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
23720 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
23730 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23740 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
23750 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
23760 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
23770 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
23780 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
23790 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
237a0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
237b0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
237c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
237d0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
237e0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
237f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
23800 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
23810 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23820 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
23830 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
23840 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
23850 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23860 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
23870 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
23880 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
23890 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
238a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
238b0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
238c0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
238d0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
238e0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
238f0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
23900 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
23910 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
23920 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
23930 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
23940 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
23950 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
23960 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
23970 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
23980 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
23990 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
239a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
239b0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
239c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
239d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
239e0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
239f0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
23a00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23a10 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
23a20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23a30 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
23a40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23a50 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
23a60 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
23a70 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
23a80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23a90 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
23aa0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
23ab0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23ac0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
23ad0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
23ae0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
23af0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
23b00 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
23b10 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
23b20 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
23b30 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
23b40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
23b50 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
23b60 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
23b70 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23b80 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
23b90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
23ba0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
23bb0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
23bc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
23bd0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
23be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
23bf0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
23c00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
23c10 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
23c20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23c30 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
23c40 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
23c50 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
23c60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
23c70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
23c80 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
23c90 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
23ca0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
23cb0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
23cc0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
23cd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
23ce0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
23cf0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
23d00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23d10 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
23d20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
23d30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23d40 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
23d50 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
23d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23d70 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
23d80 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
23d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23da0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
23db0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
23dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23dd0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
23de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
23df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23e00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
23e10 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
23e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23e30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
23e40 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
23e50 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
23e60 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
23e70 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
23e80 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
23e90 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
23ea0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
23eb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
23ec0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
23ed0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
23ee0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
23ef0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
23f00 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
23f10 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
23f20 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
23f30 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
23f40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
23f50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
23f60 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
23f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23f80 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
23f90 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
23fa0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
23fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
23fc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23fd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23fe0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
23ff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24000 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
24010 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
24020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
24030 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
24040 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
24050 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
24060 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
24070 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
24080 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
24090 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
240a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
240b0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
240c0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
240d0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
240e0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
240f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24100 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
24110 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
24120 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
24130 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
24140 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
24150 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
24160 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
24170 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
24180 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
24190 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
241a0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
241b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
241c0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
241d0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
241e0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
241f0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
24200 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
24210 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
24220 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
24230 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
24240 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
24250 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
24260 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
24270 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
24280 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
24290 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
242a0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
242b0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
242c0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
242d0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
242e0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
242f0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
24300 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
24310 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
24320 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
24330 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
24340 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
24350 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
24360 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
24370 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
24380 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
24390 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
243a0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
243b0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
243c0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
243d0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
243e0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
243f0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
24400 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
24410 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
24420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
24430 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
24440 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
24450 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
24460 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
24470 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
24480 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
24490 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
244a0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
244b0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
244c0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
244d0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
244e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
244f0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
24500 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
24510 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
24520 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
24530 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
24540 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
24550 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
24560 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
24570 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
24580 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
24590 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
245a0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
245b0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
245c0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
245d0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
245e0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
245f0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
24600 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
24610 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
24620 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
24630 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
24640 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
24650 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
24660 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
24670 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
24680 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
24690 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
246a0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
246b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
246c0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
246d0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
246e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
246f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
24700 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
24710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24720 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
24730 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
24740 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
24750 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
24760 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
24770 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
24780 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
24790 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
247a0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
247b0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
247c0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
247d0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
247e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
247f0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
24800 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
24810 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
24820 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
24830 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
24840 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
24850 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
24860 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
24870 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
24880 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
24890 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
248a0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
248b0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
248c0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
248d0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
248e0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
248f0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
24900 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
24910 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
24920 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
24930 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
24940 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
24950 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
24960 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
24970 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
24980 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
24990 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
249a0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
249b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
249c0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
249d0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
249e0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
249f0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
24a00 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
24a10 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
24a20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
24a30 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
24a40 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
24a50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
24a60 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
24a70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24a80 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
24a90 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
24aa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
24ab0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
24ac0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
24ad0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
24ae0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
24af0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
24b00 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
24b10 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
24b20 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
24b30 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
24b40 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
24b50 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
24b60 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
24b70 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
24b80 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
24b90 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
24ba0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
24bb0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
24bc0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
24bd0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
24be0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
24bf0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
24c00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
24c10 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
24c20 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
24c30 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
24c40 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
24c50 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
24c60 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
24c70 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
24c80 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
24c90 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
24ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
24cb0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
24cc0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
24cd0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
24ce0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
24cf0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
24d00 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
24d10 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
24d20 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
24d30 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
24d40 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
24d50 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
24d60 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
24d70 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
24d80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
24d90 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
24da0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
24db0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
24dc0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
24dd0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
24de0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
24df0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
24e00 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
24e10 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
24e20 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
24e30 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
24e40 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
24e50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
24e60 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
24e70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
24e80 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
24e90 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
24ea0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
24eb0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
24ec0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
24ed0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
24ee0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
24ef0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
24f00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
24f10 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
24f20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
24f30 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
24f40 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
24f50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
24f60 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
24f70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
24f80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
24f90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
24fa0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
24fb0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
24fc0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
24fd0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
24fe0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
24ff0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25000 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25010 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25020 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25030 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
25040 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
25050 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
25060 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
25070 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
25080 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
25090 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
250a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
250b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
250c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
250d0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
250e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
250f0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25100 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
25110 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25120 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25130 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
25140 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
25150 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
25160 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
25170 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
25180 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
25190 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
251a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
251b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
251c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
251d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
251e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
251f0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
25200 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25210 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25220 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25230 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
25240 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25250 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
25260 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25270 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25280 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25290 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
252a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
252b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
252c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
252d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
252e0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
252f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25300 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25310 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25320 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
25330 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
25340 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
25350 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
25360 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
25370 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
25380 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
25390 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
253a0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
253b0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
253c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
253d0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
253e0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
253f0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
25400 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25410 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
25420 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
25430 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
25440 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
25450 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
25460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25470 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
25480 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
25490 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
254a0 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
254b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
254c0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
254d0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
254e0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
254f0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
25500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25510 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
25520 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
25530 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
25540 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
25550 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
25560 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
25570 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25580 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
25590 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
255a0 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
255b0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
255c0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
255d0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
255e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
255f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
25600 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
25610 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
25620 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
25630 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
25640 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
25650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
25660 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
25670 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
25680 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
25690 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
256a0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
256b0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
256c0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
256d0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
256e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
256f0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
25700 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
25710 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
25720 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
25730 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
25740 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
25750 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
25760 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
25770 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
25780 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
25790 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
257a0 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
257b0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
257c0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
257d0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
257e0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
257f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25800 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
25810 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
25820 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
25830 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
25840 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
25850 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
25860 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
25870 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
25880 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
25890 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
258a0 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
258b0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
258c0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
258d0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
258e0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
258f0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
25900 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
25910 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
25920 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
25930 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
25940 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
25950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25960 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
25970 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
25980 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
25990 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
259a0 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
259b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
259c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
259d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
259e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
259f0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
25a00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
25a10 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
25a20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
25a30 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
25a40 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
25a50 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
25a60 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
25a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25a80 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
25a90 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
25aa0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
25ab0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25ac0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
25ad0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
25ae0 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
25af0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
25b00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
25b10 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
25b20 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
25b30 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
25b40 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
25b50 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
25b60 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
25b70 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
25b80 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
25b90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
25ba0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
25bb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
25bc0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
25bd0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25be0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25bf0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
25c00 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
25c10 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
25c20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
25c30 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
25c40 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
25c50 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
25c60 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
25c70 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
25c80 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
25c90 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
25ca0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
25cb0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
25cc0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
25cd0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
25ce0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
25cf0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
25d00 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
25d10 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
25d20 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
25d30 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
25d40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
25d50 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
25d60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25d70 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
25d80 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
25d90 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
25da0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
25db0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
25dc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25dd0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
25de0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
25df0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25e00 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
25e10 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
25e20 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
25e30 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
25e40 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
25e50 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
25e60 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
25e70 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
25e80 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
25e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25ea0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
25eb0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
25ec0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
25ed0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
25ee0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
25ef0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
25f00 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
25f10 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
25f20 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
25f30 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
25f40 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
25f50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25f60 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
25f70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
25f80 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
25f90 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
25fa0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
25fb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
25fc0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
25fd0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
25fe0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
25ff0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
26000 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
26010 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
26020 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26030 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
26040 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
26050 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
26060 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
26070 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
26080 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
26090 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
260a0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
260b0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
260c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
260d0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
260e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
260f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
26100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26110 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
26120 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
26130 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
26140 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
26150 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
26160 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
26170 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
26180 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
26190 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
261a0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
261b0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
261c0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
261d0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
261e0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
261f0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
26200 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
26210 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
26220 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
26230 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
26240 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26250 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
26260 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
26270 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
26280 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
26290 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
262a0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
262b0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
262c0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
262d0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
262e0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
262f0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
26300 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
26310 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
26320 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
26330 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
26340 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
26350 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26360 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
26370 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
26380 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
26390 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
263a0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
263b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
263c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
263d0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
263e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
263f0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
26400 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
26410 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
26420 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
26430 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
26440 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
26450 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
26460 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
26470 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
26480 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
26490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
264a0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
264b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
264c0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
264d0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
264e0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
264f0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
26500 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26510 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
26520 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
26530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
26540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26550 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
26560 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
26570 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
26580 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
26590 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
265a0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
265b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
265c0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
265d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
265e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
265f0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
26600 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26610 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
26620 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26630 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
26640 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26650 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
26660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26670 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
26680 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
26690 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
266a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
266b0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
266c0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
266d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
266e0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
266f0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
26700 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
26710 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
26720 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
26730 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
26740 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
26750 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
26760 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
26770 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
26780 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
26790 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
267a0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
267b0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
267c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
267d0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
267e0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
267f0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
26800 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
26810 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
26820 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
26830 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
26840 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
26850 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
26860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
26870 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
26880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26890 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
268a0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
268b0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
268c0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
268d0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
268e0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
268f0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
26900 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
26910 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
26920 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
26930 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
26940 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
26950 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
26960 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
26970 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
26980 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
26990 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
269a0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
269b0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
269c0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
269d0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
269e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
269f0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
26a00 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
26a10 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
26a20 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
26a30 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
26a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
26a50 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
26a60 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
26a70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26a80 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
26a90 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
26aa0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
26ab0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
26ac0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
26ad0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
26ae0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
26af0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
26b00 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
26b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
26b20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
26b30 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
26b40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
26b50 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
26b60 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
26b70 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
26b80 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
26b90 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
26ba0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
26bb0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
26bc0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
26bd0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
26be0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
26bf0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
26c00 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
26c10 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
26c20 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
26c30 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
26c40 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
26c50 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
26c60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26c70 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
26c80 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
26c90 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
26ca0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
26cb0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
26cc0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
26cd0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
26ce0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
26cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
26d00 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
26d10 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
26d20 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
26d30 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
26d40 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
26d50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
26d60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
26d70 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
26d80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
26d90 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
26da0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
26db0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
26dc0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
26dd0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
26de0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
26df0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
26e00 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
26e10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
26e20 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
26e30 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
26e40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
26e50 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
26e60 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
26e70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26e80 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
26e90 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
26ea0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
26eb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
26ec0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
26ed0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
26ee0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
26ef0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
26f00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26f10 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
26f20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
26f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26f40 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
26f50 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
26f60 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
26f70 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
26f80 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
26f90 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
26fa0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
26fb0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
26fc0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
26fd0 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
26fe0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
26ff0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
27000 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
27010 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
27020 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
27030 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
27040 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
27050 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
27060 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
27070 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
27080 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
27090 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
270a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
270b0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
270c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
270d0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
270e0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
270f0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
27100 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
27110 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
27120 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
27130 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
27140 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
27150 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
27160 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
27170 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
27180 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
27190 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
271a0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
271b0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
271c0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
271d0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
271e0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
271f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
27200 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
27210 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
27220 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
27230 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
27240 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
27250 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
27260 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
27270 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27280 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
27290 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
272a0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
272b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
272c0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
272d0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
272e0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
272f0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
27300 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
27310 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
27320 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
27330 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
27340 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
27350 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
27360 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
27370 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
27380 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
27390 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
273a0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
273b0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
273c0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
273d0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
273e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
273f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27410 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
27420 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
27430 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
27440 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
27450 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
27460 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
27470 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
27480 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
27490 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
274a0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
274b0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
274c0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
274d0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
274e0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
274f0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
27500 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
27510 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
27520 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
27530 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
27540 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
27550 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
27560 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
27570 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
27580 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
27590 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
275a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
275b0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
275c0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
275d0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
275e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
275f0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
27600 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
27610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27620 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
27630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27640 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
27650 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
27660 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
27670 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
27680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27690 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
276a0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
276b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
276c0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
276d0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
276e0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
276f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27700 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
27710 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
27720 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
27730 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
27740 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
27750 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
27760 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
27770 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
27780 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
27790 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
277a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
277b0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
277c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
277d0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
277e0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
277f0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
27800 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
27810 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
27820 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
27830 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
27840 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
27850 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27860 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
27870 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
27880 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
27890 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
278a0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
278b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
278c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
278d0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
278e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
278f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
27900 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
27910 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
27920 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
27930 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27950 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
27960 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
27970 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
27980 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
27990 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
279a0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
279b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
279c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
279d0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
279e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
279f0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
27a00 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
27a10 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
27a20 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
27a30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27a40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
27a50 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
27a60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
27a70 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
27a80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27a90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27aa0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
27ab0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
27ac0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
27ad0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27af0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
27b00 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
27b10 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
27b20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
27b30 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
27b40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27b50 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
27b60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
27b70 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
27b80 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
27b90 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
27ba0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
27bb0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
27bc0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
27bd0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27be0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
27bf0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
27c00 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
27c10 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
27c20 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
27c30 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
27c40 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
27c50 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
27c60 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
27c70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
27c80 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
27c90 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
27ca0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
27cb0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
27cc0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
27cd0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
27ce0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
27cf0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
27d00 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
27d10 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
27d20 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
27d30 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
27d40 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
27d50 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
27d60 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
27d70 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
27d80 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
27d90 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
27da0 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
27db0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27dc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
27dd0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
27de0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
27df0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
27e00 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
27e10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27e20 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
27e30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27e40 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
27e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27e60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27e70 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
27e80 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
27e90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
27ea0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
27eb0 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
27ec0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
27ed0 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
27ee0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
27ef0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
27f00 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
27f10 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
27f20 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
27f30 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
27f40 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
27f50 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
27f60 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
27f70 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
27f80 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
27f90 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
27fa0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27fb0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
27fc0 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
27fd0 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
27fe0 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
27ff0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
28000 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
28010 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
28020 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
28030 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
28040 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
28050 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
28060 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
28070 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
28080 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
28090 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
280a0 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
280b0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
280c0 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
280d0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
280e0 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
280f0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
28100 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
28110 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
28120 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
28130 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
28140 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
28150 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
28160 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
28170 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
28180 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
28190 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
281a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
281b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
281c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
281d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
281e0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
281f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
28200 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28210 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
28220 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28230 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
28240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28250 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28260 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
28270 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
28280 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
28290 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
282a0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
282b0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
282c0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
282d0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
282e0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
282f0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
28300 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
28310 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
28320 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
28330 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
28340 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
28350 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
28360 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
28370 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28380 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
28390 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
283a0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
283b0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
283c0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
283d0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
283e0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
283f0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
28400 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
28410 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
28420 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
28430 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
28440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28450 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
28460 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28470 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28480 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
28490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
284a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
284b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
284c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
284d0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
284e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
284f0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
28500 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
28510 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
28520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28530 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
28540 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
28550 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
28560 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
28570 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
28580 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
28590 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
285a0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
285b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
285c0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
285d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
285e0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
285f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
28600 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
28610 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
28620 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
28630 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
28640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28660 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
28670 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
28680 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
28690 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
286a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
286b0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
286c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
286d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
286e0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
286f0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
28700 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
28710 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
28720 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
28730 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
28740 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
28750 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28760 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
28770 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
28780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
28790 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
287a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
287b0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
287c0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
287d0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
287e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
287f0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
28800 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
28810 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
28820 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
28830 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
28840 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
28850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28860 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
28870 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
28880 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
28890 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
288a0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
288b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
288c0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
288d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
288e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
288f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
28900 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
28910 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
28920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28930 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
28940 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
28950 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
28960 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
28970 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
28980 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
28990 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
289a0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
289b0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
289c0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
289d0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
289e0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
289f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28a00 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
28a10 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
28a20 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
28a30 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
28a40 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
28a50 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
28a60 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
28a70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28a80 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
28a90 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
28aa0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
28ab0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
28ac0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
28ad0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
28ae0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
28af0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
28b00 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
28b10 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
28b20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
28b30 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
28b40 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
28b50 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
28b60 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
28b70 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
28b80 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
28b90 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
28ba0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
28bb0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
28bc0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
28bd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
28be0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
28bf0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
28c00 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
28c10 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
28c20 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
28c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
28c40 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
28c50 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
28c60 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
28c70 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
28c80 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
28c90 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
28ca0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28cb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
28cc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
28cd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
28cf0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
28d00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
28d10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
28d20 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
28d30 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
28d40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
28d50 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
28d60 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
28d70 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
28d80 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
28d90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
28da0 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
28db0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
28dc0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
28dd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
28de0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
28df0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
28e00 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
28e10 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
28e20 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
28e30 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
28e40 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
28e50 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
28e60 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
28e70 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
28e80 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
28e90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
28ea0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
28eb0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
28ec0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
28ed0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
28ee0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
28ef0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
28f00 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
28f10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28f20 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
28f30 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
28f40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28f50 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
28f60 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
28f70 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
28f80 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
28f90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28fa0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
28fb0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
28fc0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
28fd0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
28fe0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
28ff0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
29000 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
29010 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
29020 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
29030 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
29040 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
29050 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
29060 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
29070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
29080 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
29090 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
290a0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
290b0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
290c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
290d0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
290e0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
290f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
29100 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
29110 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
29120 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
29130 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
29140 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
29150 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
29160 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
29170 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
29180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
29190 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
291a0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
291b0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
291c0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
291d0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
291e0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
291f0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
29200 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
29210 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
29220 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
29230 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
29240 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
29250 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
29260 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
29270 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
29280 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
29290 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
292a0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
292b0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
292c0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
292d0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
292e0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
292f0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
29300 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
29310 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
29320 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
29330 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
29340 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
29350 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
29360 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
29370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
29380 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
29390 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
293a0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
293b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
293c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
293d0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
293e0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
293f0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
29400 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
29410 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
29420 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
29430 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
29440 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
29450 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
29460 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
29470 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
29480 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
29490 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
294a0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
294b0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
294c0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
294d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
294e0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
294f0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
29500 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
29510 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
29520 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
29530 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
29540 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
29550 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
29560 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
29570 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
29580 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29590 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
295a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
295b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
295c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
295d0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
295e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
295f0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
29600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
29610 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
29620 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29640 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
29650 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29660 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
29670 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
29680 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
29690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
296a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
296b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
296c0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
296d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
296e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
296f0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
29700 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
29710 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
29720 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29730 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
29740 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
29750 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
29760 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
29770 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
29780 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
29790 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
297a0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
297b0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
297c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
297d0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
297e0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
297f0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
29800 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
29810 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
29820 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
29830 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
29840 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29850 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
29860 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
29870 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
29880 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
29890 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
298a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
298b0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
298c0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
298d0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
298e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
298f0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
29900 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
29910 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
29920 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
29930 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
29940 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
29950 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
29960 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
29970 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
29980 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
29990 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
299a0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
299b0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
299c0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
299d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
299e0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
299f0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
29a00 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
29a10 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
29a20 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
29a30 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
29a40 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
29a50 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
29a60 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
29a70 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
29a80 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
29a90 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
29aa0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
29ab0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
29ac0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
29ad0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
29ae0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
29af0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
29b00 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
29b10 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
29b20 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
29b30 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
29b40 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
29b50 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
29b60 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
29b70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
29b90 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
29ba0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
29bb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29bc0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
29bd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29bf0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
29c00 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
29c10 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
29c20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29c30 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
29c40 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
29c50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
29c60 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29c70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29c80 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
29c90 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
29ca0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
29cb0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
29cc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29cd0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
29ce0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
29cf0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
29d00 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
29d10 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
29d20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
29d30 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
29d40 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
29d50 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
29d60 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
29d70 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
29d80 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
29d90 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
29da0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
29db0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
29dc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
29dd0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
29de0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
29df0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
29e00 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
29e10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29e20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
29e30 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
29e40 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
29e50 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
29e60 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
29e70 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
29e80 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
29e90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
29ea0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
29eb0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
29ec0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
29ed0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
29ee0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29ef0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
29f00 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
29f10 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
29f20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
29f30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
29f40 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
29f50 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
29f60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
29f70 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
29f80 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
29f90 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
29fa0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
29fb0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
29fc0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
29fd0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
29fe0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
29ff0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2a000 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2a010 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2a020 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2a030 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2a040 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2a050 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2a060 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2a070 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2a080 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2a090 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2a0a0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2a0b0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2a0c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2a0d0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2a0e0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2a0f0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2a100 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2a110 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2a120 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2a130 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2a140 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2a150 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2a160 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2a170 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2a180 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2a190 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2a1a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2a1b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2a1c0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2a1d0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2a1e0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2a1f0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2a200 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2a210 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2a220 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2a230 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2a240 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2a250 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a260 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2a270 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2a280 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2a290 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2a2a0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2a2b0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2a2c0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2a2d0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2a2e0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2a2f0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2a300 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2a310 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2a320 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2a330 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2a340 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2a350 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2a360 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2a370 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2a380 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2a390 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2a3a0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2a3b0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2a3c0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2a3d0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2a3e0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2a3f0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2a400 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2a410 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2a420 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2a430 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2a440 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2a450 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2a460 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2a470 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2a480 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2a490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2a4a0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2a4b0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2a4c0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2a4d0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2a4e0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2a4f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a500 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2a510 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2a520 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2a530 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a540 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2a550 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2a560 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2a570 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2a580 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2a590 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2a5a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2a5b0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2a5c0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2a5d0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2a5e0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2a5f0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a600 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2a610 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2a620 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2a630 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2a640 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2a650 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2a660 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2a670 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2a680 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2a690 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2a6a0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2a6b0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2a6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2a6d0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2a6e0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2a6f0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2a700 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2a710 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2a720 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2a730 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2a740 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2a750 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2a760 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2a770 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2a780 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2a790 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2a7a0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2a7b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2a7c0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2a7d0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2a7e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2a7f0 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2a800 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2a810 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2a820 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2a830 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2a840 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2a850 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2a860 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2a870 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2a880 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2a890 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2a8a0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2a8b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2a8c0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2a8d0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2a8e0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2a8f0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2a900 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2a910 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2a920 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2a930 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2a940 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2a950 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2a960 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2a970 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2a980 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2a990 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2a9a0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2a9b0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2a9c0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2a9d0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2a9e0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2a9f0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2aa00 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2aa10 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2aa20 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2aa30 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2aa40 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2aa50 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2aa60 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2aa70 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2aa80 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2aa90 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2aaa0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2aab0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2aac0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2aad0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2aae0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2aaf0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2ab00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ab10 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2ab20 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2ab30 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2ab40 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2ab50 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2ab60 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2ab70 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2ab80 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2ab90 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2aba0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2abb0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2abc0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2abd0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2abe0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2abf0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2ac00 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2ac10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2ac20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ac30 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2ac40 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2ac50 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2ac60 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2ac70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2ac80 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2ac90 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2aca0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2acb0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2acc0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2acd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2ace0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2acf0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2ad00 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2ad10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2ad20 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2ad30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ad40 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2ad50 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2ad60 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2ad70 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ad80 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2ad90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ada0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2adb0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2adc0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2add0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2ade0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2adf0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2ae00 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2ae10 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2ae20 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2ae30 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2ae40 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2ae50 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2ae60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ae70 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2ae80 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2ae90 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2aea0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2aeb0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2aec0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2aed0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2aee0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2aef0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2af00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2af10 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2af20 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2af30 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2af40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2af50 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2af60 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2af70 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2af80 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2af90 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2afa0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2afb0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2afc0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2afd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2afe0 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2aff0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2b000 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2b010 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2b020 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2b030 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2b040 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2b050 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2b060 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2b070 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2b080 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2b0a0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2b0b0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b0c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2b0d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b0e0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2b0f0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2b100 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2b110 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2b120 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2b130 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2b140 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2b150 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2b160 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2b170 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2b180 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2b190 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2b1a0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2b1b0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2b1c0 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2b1d0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2b1e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2b1f0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2b200 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2b210 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2b220 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2b230 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2b240 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2b250 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2b260 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2b270 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2b280 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2b290 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2b2a0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2b2b0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2b2c0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2b2d0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2b2e0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2b2f0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2b300 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2b310 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2b320 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2b330 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2b340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2b350 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2b360 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2b370 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2b380 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2b390 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2b3a0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2b3b0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2b3c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2b3d0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2b3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2b3f0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2b400 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2b410 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2b420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2b430 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2b440 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2b450 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2b460 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2b470 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2b480 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2b490 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2b4a0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2b4b0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2b4c0 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2b4d0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2b4e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2b4f0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2b500 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2b510 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2b520 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2b530 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2b540 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2b550 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2b560 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2b570 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2b580 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2b590 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2b5a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2b5b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2b5c0 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2b5d0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2b5e0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2b5f0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2b600 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2b610 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2b620 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2b630 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2b640 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2b650 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2b660 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2b670 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b680 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2b690 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2b6a0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2b6b0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2b6c0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2b6d0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2b6e0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2b6f0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2b700 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2b710 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2b720 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2b730 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2b740 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b750 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2b760 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2b770 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2b780 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2b790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b7a0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2b7b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2b7c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2b7d0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2b7e0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2b7f0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2b800 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2b810 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2b820 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b830 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2b840 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2b850 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2b860 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2b870 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2b880 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2b890 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2b8a0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2b8b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b8c0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2b8d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b8e0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2b8f0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2b900 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2b910 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2b920 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2b930 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2b940 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2b950 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2b960 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2b970 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2b980 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2b990 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2b9a0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2b9b0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2b9c0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2b9d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2b9e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2b9f0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2ba00 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2ba10 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2ba20 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2ba30 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2ba40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2ba50 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2ba60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ba70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ba80 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2ba90 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2baa0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2bab0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2bac0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2bad0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2bae0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2baf0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2bb00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2bb10 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2bb20 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2bb30 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2bb40 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2bb50 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2bb60 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2bb70 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2bb80 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2bb90 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2bba0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2bbb0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2bbc0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2bbd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bbe0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2bbf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2bc00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2bc10 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2bc20 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2bc30 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2bc40 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2bc50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bc60 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2bc70 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2bc80 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2bc90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2bca0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2bcb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2bcc0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2bcd0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2bce0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2bcf0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2bd00 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2bd10 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2bd20 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2bd30 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2bd40 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2bd50 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2bd60 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2bd70 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2bd80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2bd90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2bda0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2bdb0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2bdc0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2bdd0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2bde0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2bdf0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2be00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2be10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2be20 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2be30 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2be40 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2be50 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2be60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2be70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2be80 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2be90 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2bea0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2beb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2bec0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2bed0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2bee0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2bef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bf00 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2bf10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2bf20 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2bf30 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2bf40 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2bf50 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2bf60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2bf70 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2bf80 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2bf90 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2bfa0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2bfb0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2bfc0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2bfd0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2bfe0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2bff0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2c000 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2c010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c020 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2c030 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2c040 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2c050 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2c060 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2c070 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2c080 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2c090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c0a0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2c0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c0c0 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2c0d0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2c0e0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2c0f0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2c100 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2c110 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2c120 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2c130 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2c140 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2c150 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2c160 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2c170 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2c180 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2c190 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2c1a0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2c1b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2c1c0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2c1d0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2c1e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2c1f0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2c200 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2c210 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2c220 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2c230 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c240 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2c250 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2c260 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c270 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2c280 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2c290 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2c2a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2c2b0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2c2c0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2c2d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c2e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2c2f0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2c300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2c310 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2c320 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2c330 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2c340 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2c350 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2c360 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2c370 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2c380 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2c390 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2c3a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2c3b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2c3c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2c3d0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2c3e0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2c3f0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2c400 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2c410 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2c420 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2c430 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2c440 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2c450 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2c460 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2c470 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2c480 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2c490 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2c4a0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2c4b0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2c4c0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2c4d0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2c4e0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2c4f0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2c500 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2c510 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2c520 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2c530 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2c540 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2c550 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2c560 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2c570 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2c580 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2c590 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2c5a0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2c5b0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2c5c0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2c5d0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2c5e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2c5f0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2c600 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2c610 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2c620 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2c630 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2c640 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2c650 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2c660 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2c670 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2c680 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
2c690 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
2c6a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2c6b0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
2c6c0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2c6d0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2c6e0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2c6f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2c700 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2c710 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
2c720 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2c730 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2c740 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2c750 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
2c760 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
2c770 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2c780 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2c790 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2c7a0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2c7b0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2c7c0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2c7d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2c7e0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
2c7f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2c800 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2c810 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
2c820 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2c830 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2c840 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
2c850 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2c860 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2c870 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2c880 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2c890 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2c8a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2c8b0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2c8c0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2c8d0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2c8e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2c8f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2c900 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2c910 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
2c920 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2c930 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2c940 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2c950 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2c960 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2c970 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2c980 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2c990 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2c9a0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2c9b0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2c9c0 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2c9d0 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2c9e0 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2c9f0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2ca00 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2ca10 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2ca20 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2ca30 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2ca40 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2ca50 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2ca60 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2ca70 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2ca80 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2ca90 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2caa0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2cab0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2cac0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2cad0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2cae0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2caf0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2cb00 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2cb10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2cb20 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2cb30 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2cb40 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2cb50 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2cb60 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2cb70 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2cb80 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2cb90 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2cba0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2cbb0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2cbc0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2cbd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2cbe0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2cbf0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2cc00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2cc10 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cc30 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2cc40 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2cc50 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2cc60 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2cc70 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2cc80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2cc90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2cca0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2ccb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2ccc0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2ccd0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2cce0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2ccf0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2cd00 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2cd10 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2cd20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2cd30 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2cd40 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2cd50 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2cd60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cd70 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2cd80 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2cd90 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2cda0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2cdb0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2cdc0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2cdd0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2cde0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2cdf0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2ce00 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2ce10 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2ce20 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2ce30 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2ce40 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2ce50 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2ce60 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2ce70 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2ce80 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2ce90 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2cea0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2ceb0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2cec0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2ced0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2cee0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2cef0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2cf00 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2cf10 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2cf20 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2cf30 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2cf40 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2cf50 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2cf60 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2cf70 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2cf80 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2cf90 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2cfa0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2cfb0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2cfc0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2cfd0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2cfe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cff0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2d000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d010 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2d020 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2d030 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2d040 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2d050 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2d060 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2d070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d080 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2d090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d0a0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2d0b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2d0c0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2d0d0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2d0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d0f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2d100 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2d110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d120 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2d130 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2d140 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2d150 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2d160 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2d170 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d180 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2d190 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2d1a0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2d1b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2d1c0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2d1d0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2d1e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2d1f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d200 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2d210 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2d220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d230 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2d240 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2d250 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d260 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2d270 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2d280 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2d290 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2d2a0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2d2b0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2d2c0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2d2d0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2d2e0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2d2f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d300 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2d310 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2d320 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d330 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2d340 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2d350 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2d360 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2d370 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2d380 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2d390 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2d3a0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2d3b0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2d3c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2d3d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d3e0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2d3f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2d400 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
2d410 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2d420 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2d430 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2d440 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2d450 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2d460 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2d470 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2d480 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2d490 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2d4a0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2d4b0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2d4c0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2d4d0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2d4e0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2d4f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2d500 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2d510 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2d520 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
2d530 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
2d540 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d550 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2d560 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2d570 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2d580 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2d590 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d5a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d5b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2d5c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d5d0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2d5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2d5f0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2d600 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2d610 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d620 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d630 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2d640 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2d650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2d660 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d670 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2d680 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2d690 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d6a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2d6b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2d6c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d6d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d6f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2d700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d710 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2d720 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2d730 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2d740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2d750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d760 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2d770 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2d780 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2d790 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2d7a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d7b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2d7c0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2d7d0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2d7e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d7f0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2d800 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2d810 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2d820 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2d830 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
2d840 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
2d850 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
2d860 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
2d870 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2d880 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
2d890 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
2d8a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2d8b0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
2d8c0 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
2d8d0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2d8e0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
2d8f0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
2d900 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2d910 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2d920 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
2d930 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d940 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
2d950 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2d960 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2d970 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
2d980 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
2d990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d9a0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
2d9b0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
2d9c0 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
2d9d0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
2d9e0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
2d9f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
2da00 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
2da10 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2da20 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
2da30 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2da40 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
2da50 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
2da60 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
2da70 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
2da80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2da90 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
2daa0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
2dab0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
2dac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
2dad0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
2dae0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
2daf0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
2db00 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
2db10 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
2db20 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
2db30 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
2db40 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
2db50 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
2db60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2db70 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2db80 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
2db90 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
2dba0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2dbb0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2dbc0 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
2dbd0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
2dbe0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
2dbf0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
2dc00 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
2dc10 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
2dc20 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
2dc30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
2dc40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2dc50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2dc60 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
2dc70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2dc80 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2dc90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2dca0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2dcb0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2dcc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dcd0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2dce0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2dcf0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2dd00 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2dd10 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
2dd20 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2dd30 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2dd40 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2dd50 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2dd60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2dd70 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2dd80 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2dd90 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2dda0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2ddb0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2ddc0 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2ddd0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
2dde0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2ddf0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
2de00 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
2de10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2de20 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
2de30 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2de40 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2de50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2de60 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2de70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2de80 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2de90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2dea0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2deb0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2dec0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
2ded0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2dee0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2def0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2df00 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
2df10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2df20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2df30 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
2df40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2df50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2df60 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2df70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2df80 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
2df90 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
2dfa0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
2dfb0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2dfc0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2dfd0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2dfe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2dff0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2e000 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
2e010 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2e020 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
2e030 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2e040 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
2e050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e060 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
2e070 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2e080 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e090 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e0a0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2e0b0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2e0c0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2e0d0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2e0e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2e0f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2e100 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e110 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2e120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2e130 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e140 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2e150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2e160 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2e170 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2e180 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2e190 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2e1a0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2e1b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2e1c0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2e1d0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2e1e0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2e1f0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2e200 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2e210 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2e220 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2e230 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2e240 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2e250 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2e260 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2e270 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2e280 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e290 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2e2a0 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2e2b0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2e2c0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2e2d0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2e2e0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2e2f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2e300 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2e310 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e320 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2e330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2e340 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2e350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2e360 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2e370 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2e380 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2e390 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2e3a0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2e3b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e3c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2e3d0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2e3e0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2e3f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2e400 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2e410 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2e420 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2e430 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2e440 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2e450 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2e460 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2e470 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2e480 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2e490 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2e4a0 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2e4b0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2e4c0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2e4d0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2e4e0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2e4f0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2e500 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2e510 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2e520 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2e530 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2e540 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2e550 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2e560 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2e570 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2e580 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2e590 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2e5a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2e5b0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2e5c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2e5d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2e5e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2e5f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2e600 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2e610 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2e620 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2e630 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2e640 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2e650 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2e660 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2e670 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2e680 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2e690 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2e6a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2e6b0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2e6c0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2e6d0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2e6e0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2e6f0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2e700 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2e710 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2e720 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2e730 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2e740 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2e750 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2e760 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2e770 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2e780 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2e790 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2e7a0 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2e7b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2e7c0 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2e7d0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2e7e0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2e7f0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2e800 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2e810 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2e820 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2e830 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2e840 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2e850 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2e860 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2e870 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e880 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2e890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e8a0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2e8b0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2e8c0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e8d0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2e8e0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2e8f0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2e900 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2e910 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e920 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e930 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2e940 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2e950 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2e960 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2e970 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2e980 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2e990 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2e9a0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2e9b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2e9c0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2e9d0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2e9e0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2e9f0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2ea00 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2ea10 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2ea20 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
2ea30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2ea40 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2ea50 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2ea60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2ea70 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2ea80 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2ea90 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2eaa0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2eab0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
2eac0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
2ead0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
2eae0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2eaf0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2eb00 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2eb10 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2eb20 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2eb30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2eb40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2eb50 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
2eb60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2eb70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2eb80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2eb90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2eba0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
2ebb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
2ebc0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2ebd0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2ebe0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2ebf0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
2ec00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2ec10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2ec20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2ec30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2ec40 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
2ec50 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
2ec60 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
2ec70 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2ec80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2ec90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2eca0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
2ecb0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
2ecc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
2ecd0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
2ece0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
2ecf0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2ed00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ed10 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
2ed20 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
2ed30 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2ed40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ed50 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
2ed60 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
2ed70 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2ed80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2ed90 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
2eda0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
2edb0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
2edc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2edd0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
2ede0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
2edf0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
2ee00 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
2ee10 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2ee20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ee30 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
2ee40 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
2ee50 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
2ee60 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
2ee70 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
2ee80 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
2ee90 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2eea0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
2eeb0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2eec0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
2eed0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
2eee0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2eef0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2ef00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2ef10 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
2ef20 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2ef30 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2ef40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2ef50 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2ef60 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2ef70 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2ef80 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2ef90 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2efa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2efb0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2efc0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2efd0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
2efe0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2eff0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
2f000 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
2f010 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2f020 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2f030 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2f040 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
2f050 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f060 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2f070 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2f080 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2f090 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2f0a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2f0b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2f0c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2f0d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
2f0e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2f0f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2f100 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2f110 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2f120 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2f130 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2f140 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f150 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2f160 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
2f170 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f180 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2f190 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2f1a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2f1b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2f1c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2f1d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2f1e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2f1f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2f200 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2f210 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
2f220 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2f230 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2f240 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2f250 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f260 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
2f270 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2f280 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
2f290 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
2f2a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
2f2b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
2f2c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
2f2d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
2f2e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
2f2f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
2f300 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
2f310 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2f320 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2f330 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
2f340 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f360 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f370 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2f380 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2f390 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2f3a0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2f3b0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2f3c0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2f3d0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2f3e0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f3f0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f400 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2f410 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f420 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f430 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2f440 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2f450 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2f460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f470 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2f480 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f490 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2f4a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f4b0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f4c0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f4d0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f4e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f4f0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f500 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f510 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f520 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f530 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f540 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f560 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2f570 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2f580 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2f590 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2f5a0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2f5b0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2f5c0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2f5d0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2f5e0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2f5f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f600 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f610 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2f620 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f630 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2f640 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2f650 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2f660 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
2f670 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2f680 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2f690 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2f6a0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
2f6b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2f6c0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2f6d0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2f6e0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2f6f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2f700 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2f710 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2f720 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2f730 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2f740 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2f750 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2f760 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2f770 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2f780 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2f790 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2f7a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2f7b0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2f7c0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2f7d0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2f7e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f7f0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2f800 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f810 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2f820 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2f830 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2f840 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2f850 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2f860 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2f870 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2f880 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2f890 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2f8a0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2f8b0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2f8c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2f8d0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2f8e0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f8f0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2f900 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2f910 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2f920 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2f930 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2f940 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2f950 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2f960 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2f970 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2f980 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2f990 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2f9a0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2f9b0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2f9c0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2f9d0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2f9e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f9f0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2fa00 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2fa10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2fa20 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2fa30 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2fa40 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2fa50 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2fa60 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2fa70 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2fa80 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2fa90 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2faa0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2fab0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2fac0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2fad0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2fae0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2faf0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2fb00 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2fb10 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2fb20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2fb30 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2fb40 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2fb50 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2fb60 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2fb70 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2fb80 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2fb90 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2fba0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2fbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2fbc0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2fbd0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2fbe0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2fbf0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2fc00 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2fc10 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2fc20 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2fc30 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2fc40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2fc50 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2fc60 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2fc70 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2fc80 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2fc90 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2fca0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2fcb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fcc0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2fcd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fce0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2fcf0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2fd00 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2fd10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2fd20 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2fd30 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
2fd40 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2fd50 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2fd60 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2fd70 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2fd80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2fd90 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2fda0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2fdb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2fdc0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2fdd0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2fde0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2fdf0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2fe00 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2fe10 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2fe20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2fe30 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2fe40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2fe50 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2fe60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fe70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2fe80 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2fe90 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2fea0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2feb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fec0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2fed0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2fee0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2fef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ff00 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2ff10 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2ff20 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2ff30 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2ff40 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2ff50 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2ff60 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2ff70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ff80 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2ff90 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2ffa0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2ffb0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2ffc0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2ffd0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2ffe0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fff0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
30000 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
30010 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
30020 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
30030 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
30040 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
30050 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
30060 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30070 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
30080 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
30090 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
300a0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
300b0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
300c0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
300d0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
300e0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
300f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
30100 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
30110 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
30120 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
30130 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
30140 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
30150 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
30160 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
30170 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
30180 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
30190 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
301a0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
301b0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
301c0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
301d0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
301e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
301f0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
30200 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
30210 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
30220 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
30230 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
30240 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
30250 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
30260 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
30270 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
30280 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
30290 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
302a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
302b0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
302c0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
302d0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
302e0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
302f0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
30300 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30320 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30330 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
30340 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
30350 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
30360 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
30370 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
30380 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30390 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
303a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
303b0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
303c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
303d0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
303e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
303f0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
30400 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30410 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30420 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30430 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
30440 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
30450 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
30460 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
30470 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
30480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
30490 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
304a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
304b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
304c0 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
304d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
304e0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
304f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
30500 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
30510 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
30520 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
30530 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
30540 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30550 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
30560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30570 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
30580 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
30590 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
305a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
305b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
305c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
305d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
305f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30600 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30610 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30620 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
30630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30640 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
30650 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
30660 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
30670 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30680 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30690 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
306a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
306b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
306c0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
306d0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
306e0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
306f0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
30700 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
30710 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
30720 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
30730 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
30740 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
30750 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
30760 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
30770 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30780 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
30790 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
307a0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
307b0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
307c0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
307d0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
307e0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
307f0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
30800 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
30810 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
30820 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
30830 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
30840 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
30850 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
30860 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
30870 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
30880 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
30890 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
308a0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
308b0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
308c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
308d0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
308e0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
308f0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
30900 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
30910 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
30920 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
30930 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
30940 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
30950 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
30960 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
30970 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
30980 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
30990 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
309a0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
309b0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
309c0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
309d0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
309e0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
309f0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
30a00 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
30a10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30a20 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
30a30 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
30a40 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
30a50 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
30a60 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
30a70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
30a80 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
30a90 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
30aa0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
30ab0 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
30ac0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
30ad0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
30ae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
30af0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
30b00 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
30b10 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
30b20 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
30b30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30b40 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
30b50 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
30b60 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
30b70 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
30b80 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
30b90 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
30ba0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
30bb0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
30bc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30bd0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
30be0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
30bf0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
30c00 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
30c10 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
30c20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
30c30 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
30c40 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
30c50 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
30c60 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
30c70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30c80 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
30c90 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
30ca0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
30cb0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
30cc0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
30cd0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
30ce0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
30cf0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
30d00 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
30d10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
30d20 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
30d30 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
30d40 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
30d50 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
30d60 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
30d70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
30d80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
30d90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30da0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30db0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
30dc0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
30dd0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
30de0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
30df0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30e00 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
30e10 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
30e20 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
30e30 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
30e40 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
30e50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30e60 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
30e70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30e80 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
30e90 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
30ea0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
30eb0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
30ec0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
30ed0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
30ee0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30ef0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
30f00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30f10 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
30f20 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
30f30 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
30f40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30f50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
30f70 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
30f80 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
30f90 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
30fa0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
30fb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30fc0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30fd0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
30fe0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
30ff0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31010 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
31020 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
31030 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
31040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
31050 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
31060 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
31070 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
31080 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
31090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
310a0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
310b0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
310c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
310d0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
310e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
310f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
31100 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
31110 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
31120 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
31130 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
31140 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
31150 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
31160 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
31170 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31190 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
311a0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
311b0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
311c0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
311d0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
311e0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
311f0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
31200 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
31210 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
31220 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
31230 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
31240 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
31250 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
31260 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
31270 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
31280 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
31290 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
312a0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
312b0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
312c0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
312d0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
312e0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
312f0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
31300 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
31310 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
31320 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
31330 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
31340 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
31350 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
31360 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
31370 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
31380 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
31390 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
313a0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
313b0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
313c0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
313d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
313e0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
313f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
31400 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31410 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
31420 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
31430 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
31440 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
31450 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
31460 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
31470 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
31480 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
31490 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
314a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
314b0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
314c0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
314d0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
314e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
314f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
31500 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
31510 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
31520 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31530 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
31540 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
31550 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
31560 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
31570 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
31580 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
31590 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
315a0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
315b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
315c0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
315d0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
315e0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
315f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31600 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
31610 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
31620 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
31630 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
31640 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
31650 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
31660 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
31670 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
31680 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
31690 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
316a0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
316b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
316c0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
316d0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
316e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
316f0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
31700 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
31710 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
31720 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
31730 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
31740 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
31750 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
31760 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
31770 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
31780 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
31790 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
317a0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
317b0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
317c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
317d0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
317e0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
317f0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
31800 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
31810 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
31820 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
31830 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
31840 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
31850 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
31860 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
31870 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
31880 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
31890 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
318a0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
318b0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
318c0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
318d0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
318e0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
318f0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
31900 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
31910 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
31920 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
31930 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
31940 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
31950 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
31960 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
31970 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
31980 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
31990 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
319a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
319b0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
319c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
319d0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
319e0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
319f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31a00 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
31a10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31a20 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
31a30 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
31a40 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
31a50 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
31a60 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
31a70 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
31a80 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
31a90 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
31aa0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
31ab0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
31ac0 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
31ad0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
31ae0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
31af0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
31b00 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
31b10 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
31b20 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
31b30 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
31b40 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
31b50 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
31b60 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
31b70 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
31b80 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
31b90 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
31ba0 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
31bb0 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
31bc0 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
31bd0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
31be0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
31bf0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
31c00 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
31c10 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
31c20 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
31c30 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
31c40 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
31c50 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
31c60 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
31c70 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
31c80 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
31c90 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
31ca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
31cb0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
31cc0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
31cd0 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
31ce0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
31cf0 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
31d00 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
31d10 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
31d20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
31d30 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
31d40 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
31d50 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
31d60 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
31d70 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
31d80 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
31d90 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
31da0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
31db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
31dc0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
31dd0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
31de0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
31df0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
31e00 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
31e10 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
31e20 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
31e30 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
31e40 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
31e50 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
31e60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31e70 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
31e80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31e90 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
31ea0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
31eb0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
31ec0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
31ed0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
31ee0 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
31ef0 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
31f00 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
31f10 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
31f20 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
31f30 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
31f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
31f50 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
31f60 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
31f70 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
31f80 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
31f90 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
31fa0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31fb0 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
31fc0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31fd0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
31fe0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31ff0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32000 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
32010 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
32020 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
32030 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32040 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
32050 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
32060 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
32070 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
32080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32090 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
320a0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
320b0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
320c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
320d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
320e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
320f0 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
32100 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
32110 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
32120 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
32130 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
32140 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
32150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32160 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
32170 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32180 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
32190 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
321a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
321b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
321c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
321d0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
321e0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
321f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
32200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32210 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
32220 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32230 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
32240 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
32250 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
32260 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
32270 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
32280 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
32290 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
322a0 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
322b0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
322c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
322d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
322e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
322f0 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
32300 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
32310 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
32320 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
32330 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
32340 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
32350 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
32360 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
32370 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
32380 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
32390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
323a0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
323b0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
323c0 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
323d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
323e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
323f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
32400 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
32410 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
32420 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
32430 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
32440 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
32450 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
32460 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
32470 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
32480 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
32490 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
324a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
324b0 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
324c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
324d0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
324e0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
324f0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
32500 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
32510 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
32520 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32530 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
32540 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
32550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32560 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
32570 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32580 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
32590 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
325a0 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
325b0 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
325c0 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
325d0 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
325e0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
325f0 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
32600 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
32610 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
32620 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
32630 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
32640 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32650 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
32660 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
32670 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
32680 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
32690 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
326a0 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
326b0 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
326c0 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
326d0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
326e0 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
326f0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
32700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32710 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
32720 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32730 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
32740 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
32750 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
32760 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32770 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
32780 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
32790 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
327a0 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
327b0 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
327c0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
327d0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
327e0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
327f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32800 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
32810 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
32820 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
32830 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
32840 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
32850 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
32860 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
32870 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32880 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
32890 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
328a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
328b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
328c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
328d0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
328e0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
328f0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
32900 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
32910 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
32920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32930 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
32940 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
32950 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
32960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32970 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32980 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
32990 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
329a0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
329b0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
329c0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
329d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
329e0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
329f0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
32a00 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
32a10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32a20 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32a30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
32a40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32a50 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
32a60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
32a70 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
32a80 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
32a90 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
32aa0 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
32ab0 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
32ac0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32ad0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32ae0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32af0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
32b00 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
32b10 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
32b20 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
32b30 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
32b40 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
32b50 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
32b60 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
32b70 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
32b80 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
32b90 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
32ba0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
32bb0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
32bc0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
32bd0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
32be0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32bf0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
32c00 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
32c10 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
32c20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
32c30 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
32c40 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
32c50 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
32c60 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
32c70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
32c80 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
32c90 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
32ca0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
32cb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
32cc0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32cd0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32ce0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
32cf0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
32d00 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
32d10 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
32d20 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
32d30 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
32d40 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
32d50 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
32d60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
32d70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
32d80 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
32d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
32da0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
32db0 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
32dc0 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
32dd0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
32de0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
32df0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
32e00 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
32e10 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
32e20 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
32e30 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
32e40 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
32e50 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
32e60 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
32e70 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
32e80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
32e90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
32ea0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
32eb0 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
32ec0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
32ed0 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
32ee0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
32ef0 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
32f00 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
32f10 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
32f20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
32f30 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32f40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32f50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32f60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
32f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32f80 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
32f90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
32fa0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
32fb0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
32fc0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
32fd0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
32fe0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
32ff0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
33000 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
33010 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
33020 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
33030 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
33040 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
33050 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
33060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33070 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
33080 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
33090 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
330a0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
330b0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
330c0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
330d0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
330e0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
330f0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
33100 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
33110 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
33120 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
33130 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
33140 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
33150 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
33160 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
33170 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33180 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33190 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
331a0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
331b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
331c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
331d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
331e0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
331f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
33200 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
33210 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
33220 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
33230 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
33240 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
33250 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
33260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33270 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
33280 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33290 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
332a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
332b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
332c0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
332d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
332e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
332f0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
33300 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33310 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
33320 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33330 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
33340 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
33350 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
33360 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
33370 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33380 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
33390 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
333a0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
333b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
333c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
333d0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
333e0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
333f0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
33400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33410 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
33420 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
33430 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
33440 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33450 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
33460 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
33470 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
33480 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33490 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
334a0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
334b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
334c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
334d0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
334e0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
334f0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
33500 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
33510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33520 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33530 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
33540 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
33550 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
33560 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
33570 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
33580 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33590 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
335a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
335b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
335c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
335d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
335e0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
335f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
33600 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
33610 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
33620 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
33640 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33650 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
33660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33670 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33680 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
33690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
336a0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
336b0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
336c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
336d0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
336e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
336f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33700 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
33710 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
33720 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33730 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
33740 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
33750 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33760 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
33770 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
33780 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
33790 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
337a0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
337b0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
337c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
337d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
337e0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
337f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
33800 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
33810 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33820 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
33830 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33840 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
33850 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
33860 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33870 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
33880 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
33890 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
338a0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
338b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
338c0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
338d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
338e0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
338f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
33900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33910 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
33920 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
33930 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
33940 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
33950 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
33960 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
33970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
33980 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
33990 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
339a0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
339b0 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
339c0 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
339d0 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
339e0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
339f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33a00 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
33a10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
33a20 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
33a30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
33a40 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
33a50 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
33a60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
33a70 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
33a80 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33a90 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
33aa0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
33ab0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
33ac0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
33ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33ae0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
33af0 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
33b00 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
33b10 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
33b20 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
33b30 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
33b40 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
33b50 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
33b60 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
33b70 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
33b80 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
33b90 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
33ba0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
33bb0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
33bc0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
33bd0 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
33be0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
33bf0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
33c00 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
33c10 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
33c20 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
33c30 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
33c40 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
33c50 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
33c60 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
33c70 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
33c80 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
33c90 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
33ca0 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
33cb0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
33cc0 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
33cd0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
33ce0 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
33cf0 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
33d00 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
33d10 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
33d20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
33d30 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
33d40 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
33d50 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
33d60 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
33d70 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
33d80 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
33d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
33da0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
33db0 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
33dc0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
33dd0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
33de0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
33df0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33e00 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
33e10 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
33e20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
33e30 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
33e40 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
33e50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
33e60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33e70 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
33e80 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33e90 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
33ea0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
33eb0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
33ec0 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
33ed0 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
33ee0 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
33ef0 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
33f00 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
33f10 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
33f20 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
33f30 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
33f40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
33f50 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
33f60 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
33f70 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33f80 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
33f90 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
33fa0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33fb0 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
33fc0 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
33fd0 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
33fe0 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
33ff0 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
34000 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
34010 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
34020 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
34030 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
34040 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
34050 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
34060 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
34070 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
34080 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
34090 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
340a0 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
340b0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
340c0 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
340d0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
340e0 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
340f0 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
34100 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
34110 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
34120 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
34130 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
34140 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
34150 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
34160 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
34170 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
34180 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
34190 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
341a0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
341b0 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
341c0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
341d0 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
341e0 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
341f0 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
34200 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
34210 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
34220 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
34230 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
34240 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
34250 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
34260 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
34270 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
34280 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34290 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
342a0 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
342b0 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
342c0 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
342d0 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
342e0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
342f0 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
34300 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
34310 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
34320 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
34330 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
34340 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
34350 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
34360 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
34370 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
34380 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
34390 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
343a0 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
343b0 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
343c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
343d0 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
343e0 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
343f0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
34400 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
34410 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34420 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34430 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
34440 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
34450 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34460 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
34470 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
34480 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
34490 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
344a0 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
344b0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
344c0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
344d0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
344e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
344f0 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
34500 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
34510 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
34520 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
34530 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
34540 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
34550 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
34560 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
34570 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
34580 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
34590 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
345a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
345b0 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
345c0 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
345d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
345e0 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
345f0 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
34600 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
34610 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
34620 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34630 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
34640 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
34650 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
34660 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
34670 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
34680 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
34690 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
346a0 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
346b0 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
346c0 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
346d0 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
346e0 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
346f0 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
34700 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
34710 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
34720 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
34730 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
34740 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
34750 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
34760 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
34770 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
34780 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
34790 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
347a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
347b0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
347c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
347d0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
347e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
347f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
34800 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
34810 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
34820 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
34830 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
34840 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
34850 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34860 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34870 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
34880 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34890 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
348a0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
348b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
348c0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
348d0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
348e0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
348f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34900 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34910 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
34920 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
34930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34940 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34950 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34960 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
34970 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
34980 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
34990 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
349a0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
349b0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
349c0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
349d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
349e0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
349f0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
34a00 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
34a10 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
34a20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
34a30 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
34a40 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
34a50 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
34a60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
34a70 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
34a80 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
34a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34aa0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
34ab0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
34ac0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
34ad0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
34ae0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
34af0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
34b00 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
34b10 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
34b20 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34b30 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
34b40 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
34b50 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
34b60 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
34b70 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
34b80 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
34b90 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
34ba0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34bb0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
34bc0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
34bd0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
34be0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
34bf0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
34c00 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
34c10 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
34c20 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
34c30 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
34c40 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
34c50 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
34c60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
34c70 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
34c80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
34c90 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
34ca0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
34cb0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
34cc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34cd0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
34ce0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34cf0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
34d00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
34d10 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
34d20 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
34d30 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34d40 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
34d50 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
34d60 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
34d70 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
34d80 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
34d90 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
34da0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
34db0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
34dc0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
34dd0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
34de0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
34df0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
34e00 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
34e10 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
34e20 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
34e30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
34e40 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
34e50 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
34e60 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
34e70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34e80 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
34e90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34ea0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
34eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
34ec0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
34ed0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
34ee0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34ef0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
34f00 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
34f10 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34f20 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34f30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34f40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
34f50 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34f60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34f70 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
34f80 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
34f90 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
34fa0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
34fb0 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
34fc0 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
34fd0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
34fe0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
34ff0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
35000 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
35010 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
35020 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
35030 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
35040 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
35050 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
35060 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
35070 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
35080 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
35090 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
350a0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
350b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
350c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
350d0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
350e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
350f0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
35100 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
35110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
35120 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
35130 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
35140 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
35150 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
35160 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
35170 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
35180 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
35190 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
351a0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
351b0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
351c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
351d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
351e0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
351f0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
35200 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
35210 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
35220 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
35230 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35250 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
35260 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
35270 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
35280 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
35290 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
352a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
352b0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
352c0 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
352d0 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
352e0 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
352f0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
35300 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
35310 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
35320 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
35330 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
35340 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
35350 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
35360 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
35370 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
35380 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
35390 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
353a0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
353b0 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
353c0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
353d0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
353e0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
353f0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
35400 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
35410 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
35420 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
35430 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
35440 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
35450 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
35460 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
35470 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
35480 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
35490 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
354a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
354b0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
354c0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
354d0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
354e0 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
354f0 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
35500 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
35510 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
35520 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
35530 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
35540 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
35550 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
35560 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
35570 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
35580 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
35590 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
355a0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
355b0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
355c0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
355d0 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
355e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
355f0 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
35600 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
35610 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
35620 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
35630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
35640 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
35650 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
35660 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
35670 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
35680 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
35690 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
356a0 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
356b0 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
356c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
356d0 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
356e0 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
356f0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
35700 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
35710 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
35720 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
35730 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
35740 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
35750 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
35760 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
35770 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35780 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
35790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
357a0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
357b0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
357c0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
357d0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
357e0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
357f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
35800 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
35810 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
35820 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
35830 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
35840 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
35850 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
35860 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
35870 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
35880 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
35890 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
358a0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
358b0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
358c0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
358d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
358e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
358f0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
35900 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
35910 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
35920 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
35930 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
35940 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
35950 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
35960 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
35970 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
35980 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
35990 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
359a0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
359b0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
359c0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
359d0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
359e0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
359f0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
35a00 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
35a10 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
35a20 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
35a30 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
35a40 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
35a50 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
35a60 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
35a70 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
35a80 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
35a90 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
35aa0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
35ab0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
35ac0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
35ad0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
35ae0 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
35af0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
35b00 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
35b10 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
35b20 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
35b30 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
35b40 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
35b50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
35b60 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
35b70 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
35b80 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
35b90 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
35ba0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
35bb0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
35bc0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
35bd0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
35be0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35bf0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
35c00 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
35c10 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
35c20 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
35c30 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
35c40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
35c50 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
35c60 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
35c70 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
35c80 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
35c90 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
35ca0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
35cb0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
35cc0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
35cd0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
35ce0 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
35cf0 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
35d00 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
35d10 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
35d20 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  oided..**.** <b>
35d30 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
35d40 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
35d50 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
35d60 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
35d70 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
35d80 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   to calling [sql
35d90 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73  ite3_open] or [s
35da0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e  qlite3_open_v2].
35db0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
35dc0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
35dd0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
35de0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
35df0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
35e00 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a  l.  Here is an.*
35e10 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77  * example of how
35e20 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e   to do this usin
35e30 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57  g C++ with the W
35e40 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a  indows Runtime:.
35e50 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
35e60 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53  e><pre>.** LPCWS
35e70 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f  TR zPath = Windo
35e80 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70  ws::Storage::App
35e90 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75  licationData::Cu
35ea0 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70  rrent->.** &nbsp
35eb0 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46  ;     TemporaryF
35ec0 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74  older->Path->Dat
35ed0 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61  a();.** char zPa
35ee0 74 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41  thBuf&#91;MAX_PA
35ef0 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20  TH + 1&#93;;.** 
35f00 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c  memset(zPathBuf,
35f10 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68   0, sizeof(zPath
35f20 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68  Buf));.** WideCh
35f30 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50  arToMultiByte(CP
35f40 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c  _UTF8, 0, zPath,
35f50 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73   -1, zPathBuf, s
35f60 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c  izeof(zPathBuf),
35f70 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e  .** &nbsp;     N
35f80 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73  ULL, NULL);.** s
35f90 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
35fa0 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f  ctory = sqlite3_
35fb0 6d 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50  mprintf("%s", zP
35fc0 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72  athBuf);.** </pr
35fd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
35fe0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
35ff0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
36000 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
36010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36020 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
36030 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62  er Holding Datab
36040 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ase Files.**.** 
36050 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
36060 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
36070 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
36080 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
36090 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
360a0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
360b0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
360c0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
360d0 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  les.** specified
360e0 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
360f0 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72   pathname and cr
36100 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65  eated or accesse
36110 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77  d by.** SQLite w
36120 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
36130 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71  t-in windows [sq
36140 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
36150 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64   will be assumed
36160 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69  .** to be relati
36170 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63  ve to that direc
36180 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73  tory.)^ ^If this
36190 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
361a0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ULL.** pointer, 
361b0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
361c0 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74  mes that all dat
361d0 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63  abase files spec
361e0 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  ified.** with a 
361f0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
36200 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74  e are relative t
36210 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  o the current di
36220 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74  rectory.** for t
36230 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c  he process.  Onl
36240 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  y the windows VF
36250 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74  S makes use of t
36260 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61  his global.** va
36270 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67  riable; it is ig
36280 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69  nored by the uni
36290 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61  x VFS..**.** Cha
362a0 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  nging the value 
362b0 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  of this variable
362c0 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73   while a databas
362d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a  e connection is.
362e0 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75  ** open can resu
362f0 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20  lt in a corrupt 
36300 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
36310 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
36320 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
36330 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36340 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
36350 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
36360 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
36370 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
36380 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36390 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
363a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
363b0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
363c0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
363d0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
363e0 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
363f0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
36400 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
36410 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
36420 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
36430 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
36440 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
36450 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36460 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
36470 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
36480 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36490 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
364a0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
364b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
364c0 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
364d0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
364e0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
364f0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
36500 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
36510 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
36520 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
36530 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
36540 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
36550 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
36560 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
36570 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
36580 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
36590 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
365a0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
365b0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
365c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
365d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
365e0 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
365f0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
36600 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
36610 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
36620 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
36630 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
36640 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
36650 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
36660 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
36670 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
36680 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
36690 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
366a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
366b0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
366c0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
366d0 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
366e0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
366f0 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
36700 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
36710 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
36720 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a  data_directory;.
36730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36740 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
36750 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
36760 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
36770 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
36780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
36790 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
367a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
367b0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
367c0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
367d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
367e0 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
367f0 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
36800 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
36810 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
36820 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
36830 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
36840 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36850 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
36860 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
36870 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
36880 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
36890 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
368a0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
368b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
368c0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
368d0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
368e0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
368f0 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
36900 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
36910 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
36920 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
36930 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
36940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
36950 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
36960 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
36970 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
36980 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
36990 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
369a0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
369b0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
369c0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
369d0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
369e0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
369f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
36a00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
36a10 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
36a20 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
36a30 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
36a40 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
36a50 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
36a60 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
36a70 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
36a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
36a90 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
36aa0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
36ab0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36ac0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
36ad0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36ae0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
36af0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
36b00 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
36b10 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
36b20 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
36b30 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
36b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36b50 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
36b60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
36b70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36b80 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
36b90 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
36ba0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36bb0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
36bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36bd0 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
36be0 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
36bf0 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
36c00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36c10 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
36c20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
36c30 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
36c40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
36c50 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
36c60 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
36c70 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
36c80 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
36c90 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
36ca0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
36cb0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
36cc0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
36cd0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
36ce0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
36cf0 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
36d00 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
36d10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
36d20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
36d30 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
36d40 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36d50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
36d60 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
36d70 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
36d80 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
36d90 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
36da0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
36db0 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
36dc0 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
36dd0 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
36de0 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on th
36df0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
36e00 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69  nnection D, or i
36e10 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20  f database N is 
36e20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69  a temporary or i
36e30 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
36e40 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c  e, then.** a NUL
36e50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
36e60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
36e70 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72  e filename retur
36e80 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
36e90 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70  tion is the outp
36ea0 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75  ut of the.** xFu
36eb0 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f  llPathname metho
36ec0 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20  d of the [VFS]. 
36ed0 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   ^In other words
36ee0 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  , the filename.*
36ef0 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73  * will be an abs
36f00 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20  olute pathname, 
36f10 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65  even if the file
36f20 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20  name used.** to 
36f30 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
36f40 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73  e originally was
36f50 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69   a URI or relati
36f60 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a  ve pathname..*/.
36f70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
36f80 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
36f90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
36fa0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
36fb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36fc0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66  EF: Determine if
36fd0 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72   a database is r
36fe0 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e  ead-only.**.** ^
36ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  The sqlite3_db_r
37000 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74  eadonly(D,N) int
37010 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31  erface returns 1
37020 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
37030 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74   N.** of connect
37040 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e  ion D is read-on
37050 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72  ly, 0 if it is r
37060 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31  ead/write, or -1
37070 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20   if N is not.** 
37080 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61  the name of a da
37090 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63  tabase on connec
370a0 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73  tion D..*/.int s
370b0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
370c0 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  ly(sqlite3 *db, 
370d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
370e0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
370f0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
37100 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
37110 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
37120 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
37130 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
37140 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
37150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37160 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
37170 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37180 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37190 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
371a0 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
371b0 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
371c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
371d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
371e0 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
371f0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
37200 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
37210 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37220 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
37230 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
37240 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
37250 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
37260 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
37270 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
37280 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
37290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
372a0 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
372b0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
372c0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
372d0 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
372e0 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
372f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
37300 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
37310 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
37320 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
37330 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
37340 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
37350 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
37360 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
37370 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
37380 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
37390 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
373a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
373b0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
373c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
373d0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
373e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
373f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
37400 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37410 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
37420 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
37430 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
37440 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
37450 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
37460 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
37470 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
37480 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
37490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
374a0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
374b0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
374c0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
374d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
374e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
374f0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
37500 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
37510 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
37520 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
37530 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
37540 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
37550 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37560 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
37570 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37580 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
37590 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
375a0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
375b0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
375c0 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
375d0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
375e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
375f0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
37600 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
37610 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
37620 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
37630 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
37640 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
37650 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
37660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37670 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
37680 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
37690 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
376a0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
376b0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
376c0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
376d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
376e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
376f0 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
37700 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
37710 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
37720 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
37730 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
37740 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
37750 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f   D..**.** The co
37760 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63  mmit and rollbac
37770 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73  k hook callbacks
37780 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61   are not reentra
37790 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  nt..** The callb
377a0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
377b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
377c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
377d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
377e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
377f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
37800 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
37810 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
37820 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
37830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37840 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
37850 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
37860 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
37870 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37880 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
37890 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
378a0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
378b0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
378c0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
378d0 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e  * Note that runn
378e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
378f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e  L statements, in
37900 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73  cluding SELECT s
37910 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72  tatements,.** or
37920 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20   merely calling 
37930 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37940 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
37950 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
37960 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
37970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37980 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
37990 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
379a0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
379b0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
379c0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
379d0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
379e0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
379f0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
37a00 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
37a10 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
37a20 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
37a30 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
37a40 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
37a50 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
37a60 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
37a70 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
37a80 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
37a90 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
37aa0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
37ab0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
37ac0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
37ad0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
37ae0 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
37af0 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
37b00 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
37b10 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
37b20 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
37b30 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
37b40 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
37b50 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
37b60 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
37b70 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
37b80 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
37b90 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
37ba0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
37bb0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
37bc0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
37bd0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
37be0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
37bf0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
37c00 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
37c10 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
37c20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
37c30 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
37c40 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
37c50 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
37c60 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
37c70 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
37c80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37c90 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
37ca0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37cb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
37cc0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
37cd0 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
37ce0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
37cf0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
37d00 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
37d10 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
37d20 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37d30 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
37d40 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
37d50 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
37d60 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
37d70 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
37d80 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
37d90 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
37da0 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
37db0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37dc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37dd0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
37de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37df0 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
37e00 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
37e10 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
37e20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37e30 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
37e40 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
37e50 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
37e60 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37e70 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37e80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
37e90 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
37ea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37eb0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
37ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
37ed0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
37ee0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37ef0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
37f00 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
37f10 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
37f20 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
37f30 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
37f40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37f50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
37f60 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
37f70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
37f80 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37f90 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
37fa0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
37fb0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
37fc0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
37fd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
37fe0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
37ff0 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
38000 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
38010 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
38020 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
38030 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
38040 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
38050 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
38060 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
38070 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
38080 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
38090 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
380a0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
380b0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
380c0 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
380d0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
380e0 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
380f0 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
38100 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
38110 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
38120 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
38130 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
38140 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
38150 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
38160 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
38170 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
38180 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
38190 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
381a0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
381b0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
381c0 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
381d0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
381e0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
381f0 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
38200 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
38210 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
38220 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
38230 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
38240 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
38250 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
38260 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
38270 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
38280 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
38290 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
382a0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
382b0 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
382c0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
382d0 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
382e0 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
382f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
38300 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
38310 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
38320 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
38330 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
38340 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
38350 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
38360 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
38370 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
38380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38390 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
383a0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
383b0 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
383c0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
383d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
383e0 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
383f0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
38400 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
38410 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
38420 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
38430 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
38440 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
38450 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
38460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
38470 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38480 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
38490 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
384a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
384b0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
384c0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
384d0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
384e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
384f0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38500 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
38510 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
38520 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
38530 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
38540 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
38550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38560 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
38570 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
38580 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
38590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
385a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
385b0 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
385c0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
385d0 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
385e0 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  aces..*/.void *s
385f0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
38600 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
38610 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
38620 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
38630 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
38640 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
38650 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
38660 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
38670 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
38680 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
38690 65 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  e.**.** ^(This r
386a0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
386b0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
386c0 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
386d0 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
386e0 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
386f0 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
38700 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
38710 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63  nection | connec
38720 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65  tions].** to the
38730 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
38740 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
38750 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
38760 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e  nt is true.** an
38770 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
38780 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61  e argument is fa
38790 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  lse.)^.**.** ^Ca
387a0 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
387b0 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
387c0 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
387d0 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  e process..** Th
387e0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
387f0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
38800 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
38810 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
38820 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
38830 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
38840 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r