/ Hex Artifact Content
Login

Artifact 095fc633527cb18e5196ea5adc31370dc6aa389e:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a60: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a80: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4a90: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4aa0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ab0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ac0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ad0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ae0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4af0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b10: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b20: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4b40: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4b50: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b80: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4b90: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4ba0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4bb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4bc0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4bd0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4be0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4bf0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4c00: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4c20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4c30: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4c40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c50: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4c60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4c70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4c80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4c90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ca0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4cb0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4cc0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4cd0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ce0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4cf0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d00: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d10: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4d20: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4d40: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4d50: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4d60: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4d70: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4d80: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d90: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4da0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4db0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4dc0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4dd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4de0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4df0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e00: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e10: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4e20: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e30: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4e40: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4e50: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4e60: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4e70: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4e80: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4e90: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ea0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4eb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ec0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4ed0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4ee0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4ef0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4f00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4f10: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4f20: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4f30: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4f40: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4f50: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4f60: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f80: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4fc0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4fe0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5010: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5080: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5200: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5210: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
52c0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5530: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5550: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5570: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5580: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5590: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
55c0: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
55d0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
55e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55f0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5600: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5610: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5620: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5630: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5640: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5650: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5660: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5670: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5680: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5690: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56b0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56e0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5700: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5710: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5720: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5740: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5750: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5760: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
5780: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
5790: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
57a0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
57b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
57c0: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
57d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
57e0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5810: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5820: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5840: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5850: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5860: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5870: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5880: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5890: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
58a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58b0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
58c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
58d0: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
58e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
58f0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5910: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5920: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5930: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5940: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
5960: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5980: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5990: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59a0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
59b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59c0: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
59d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59e0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
59f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a00: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5a10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5a20: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5a30: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5a40: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5a50: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5a60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5a70: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5a80: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5a90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5aa0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5ab0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5ac0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5ad0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5ae0: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5af0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b00: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5b10: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5b20: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b30: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b50: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5b60: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5b70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ba0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5bb0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5bc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5be0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5bf0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5c00: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5c10: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c30: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5c40: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5c50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c70: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5c80: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5c90: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5cc0: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5cd0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5ce0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d00: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5d10: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5d20: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d30: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d50: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5d60: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5d70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d90: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5da0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5db0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dd0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5de0: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5df0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5e20: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5e60: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5ea0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5ee0: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5f20: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5f30: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f40: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f60: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5f70: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5f80: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f90: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5fa0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fb0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
5fc0: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
5fd0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5fe0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6000: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6010: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6020: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6030: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6040: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6050: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
6060: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
6070: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
6080: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
6090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
60a0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
60b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
60c0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
60d0: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
60e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
60f0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6100: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6110: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6120: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6130: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6140: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6150: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
6160: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
6170: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
6180: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
6190: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
61a0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
61b0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
61c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
61d0: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
61e0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
61f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6200: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6210: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6220: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6230: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6240: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6250: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6260: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6270: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6280: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6290: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
62a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
62b0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
62c0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
62d0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
62e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
62f0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6300: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6310: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6320: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6330: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6340: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6350: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6360: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6370: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6380: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6390: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
63a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63b0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
63c0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
63d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
63e0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
63f0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6400: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6410: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6430: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6440: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6450: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
6460: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
6470: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
6480: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
6490: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
64a0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
64b0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
64c0: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
64d0: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
64e0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
64f0: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6500: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6510: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6520: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6530: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6540: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6550: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6560: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6570: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6590: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
65a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
65b0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
65c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
65d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
65e0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
65f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6600: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6610: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6630: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6640: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6650: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6660: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6670: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6680: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66a0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
66b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
66c0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
66d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
66e0: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
66f0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6710: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6720: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6730: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6740: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6750: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6760: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6780: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6790: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
67a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
67b0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
67c0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
67d0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
67e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
67f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6800: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6810: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6820: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6830: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6840: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6850: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6860: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6870: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6880: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6890: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
68a0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
68b0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
68c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
68d0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
68e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
68f0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6910: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6920: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6930: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6940: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6950: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6960: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6980: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6990: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
69a0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
69b0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
69c0: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
69d0: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
69e0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
69f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6a00: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6a10: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6a20: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6a30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6a40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6a50: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6a60: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6a70: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6a80: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6a90: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6aa0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6ab0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6ac0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6ad0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6ae0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6af0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6b00: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6b10: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6b20: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6b30: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6b40: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6b50: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6b60: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6b70: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6b80: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6b90: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6ba0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6bb0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6bc0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6bd0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6be0: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6bf0: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6c00: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6c10: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6c20: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6c30: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6c40: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6c50: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6c60: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6c70: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6c80: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6c90: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6ca0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6cb0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6cc0: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6cd0: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6ce0: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6cf0: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6d00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6d10: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6d20: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6d30: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6d40: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6d50: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6d60: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6d70: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6d80: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6d90: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6da0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6db0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6dc0: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6dd0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6de0: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6df0: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6e00: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6e10: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e20: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6e30: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6e40: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6e50: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6e60: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6e70: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6e80: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6e90: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6ea0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6eb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6ec0: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6ed0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6ee0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6ef0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6f00: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6f10: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6f20: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6f30: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6f40: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6f50: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
6f60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6f70: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6f80: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6f90: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
6fa0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
6fb0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
6fc0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
6fd0: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
6fe0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
6ff0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7000: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7010: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7020: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7030: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7040: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7050: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7060: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7070: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7080: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7090: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
70a0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
70b0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
70c0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
70d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70e0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
70f0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7100: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7110: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7120: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7130: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7140: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7150: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7160: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7170: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7180: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7190: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
71a0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
71b0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
71c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
71d0: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
71e0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
71f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7200: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7210: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7220: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7230: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7240: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7250: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7260: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7270: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7280: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7290: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
72a0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
72b0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
72c0: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
72d0: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
72e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
72f0: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7300: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7310: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7320: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7330: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7340: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7350: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7360: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7370: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7380: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7390: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
73a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
73b0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
73c0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
73d0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
73e0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
73f0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7400: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7410: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7420: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7430: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7440: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7450: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7460: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7470: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7480: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7490: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
74a0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
74b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
74c0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
74d0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
74e0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
74f0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7500: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7510: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7520: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7530: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7540: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7550: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
7560: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7570: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7580: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7590: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
75a0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
75b0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
75c0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
75d0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
75e0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
75f0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7600: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7610: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7620: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7630: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7640: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7650: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
7660: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7670: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7680: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7690: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
76a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
76b0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
76c0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
76d0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
76e0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
76f0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7700: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7710: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7730: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7740: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7750: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7760: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7770: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7780: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7790: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
77a0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
77b0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
77c0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
77d0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
77e0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
77f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7800: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7810: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7820: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7830: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7840: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7850: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7860: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7870: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7880: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7890: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
78a0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
78b0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
78c0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
78d0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
78e0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
78f0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7900: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7910: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7920: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7930: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7940: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7950: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7960: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7970: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7980: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7990: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
79a0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
79b0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
79c0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
79d0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
79e0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
79f0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7a00: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7a10: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7a20: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7a30: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7a40: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7a50: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7a60: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7a70: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7a80: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7a90: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ab0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7ac0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7ad0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7ae0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7af0: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7b00: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7b10: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7b20: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7b30: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7b40: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7b50: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7b60: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7b70: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7b80: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7b90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7ba0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7bb0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7bc0: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7bd0: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7be0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7bf0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7c00: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7c10: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7c20: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7c30: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7c40: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7c50: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7c60: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7c70: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7c80: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7c90: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7ca0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7cb0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7cc0: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7cd0: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7ce0: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7cf0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7d00: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7d10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7d20: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7d30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7d40: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7d50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7d60: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7d70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7d80: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7d90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7db0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7dc0: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7dd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7de0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7df0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e00: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7e10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e20: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7e30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e40: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7e50: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7e60: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7e70: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7e80: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7e90: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7ea0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7eb0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7ec0: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7ed0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7ee0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7ef0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7f00: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7f10: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7f20: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7f30: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7f40: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7f50: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7f60: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7f70: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7f80: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7f90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7fa0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7fb0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7fc0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7fd0: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7fe0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
7ff0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8000: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8010: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8020: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8030: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8040: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8050: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
8060: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
8070: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
8080: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
8090: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
80a0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
80b0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
80c0: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
80d0: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
80e0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
80f0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8100: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8110: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8120: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8130: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8140: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8150: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
8160: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
8170: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
8180: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
8190: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
81a0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
81b0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
81c0: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
81d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
81e0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
81f0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8200: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8210: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8220: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8230: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8240: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8250: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8260: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
8270: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
8280: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8290: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
82a0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
82b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
82c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
82d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
82e0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
82f0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8300: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8310: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8320: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8330: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8340: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8350: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
8360: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8370: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
8380: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
8390: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
83a0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
83b0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
83c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
83d0: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
83e0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
83f0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8400: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8410: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8420: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8430: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8440: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8450: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8460: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
8470: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8480: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
8490: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
84a0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
84b0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
84c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
84d0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
84e0: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
84f0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8500: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8510: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8520: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8530: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8540: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8550: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8560: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8570: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8580: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8590: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
85a0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
85b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
85c0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
85d0: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
85e0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
85f0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8600: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8610: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8620: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8630: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8640: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8650: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8660: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8670: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8680: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8690: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
86a0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
86b0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
86c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
86d0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
86e0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86f0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8700: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8710: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8720: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8730: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8740: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8750: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8760: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8770: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8780: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8790: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
87a0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
87b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
87c0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
87d0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
87e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
87f0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8800: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8810: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8820: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8830: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8840: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8850: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8860: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8870: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8880: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8890: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
88a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
88b0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
88c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
88d0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
88e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
88f0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8900: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8910: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8920: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8930: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8940: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8950: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8960: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8970: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8980: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8990: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
89a0: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
89b0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
89c0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
89d0: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
89e0: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
89f0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8a00: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8a10: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8a20: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8a30: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8a40: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8a50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8a60: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8a70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8a80: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8a90: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8aa0: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ab0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8ac0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8ad0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ae0: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8af0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8b00: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8b10: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8b20: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8b30: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8b40: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8b50: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8b60: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8b70: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8b80: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8b90: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8ba0: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8bb0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8bc0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
8bd0: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
8be0: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
8bf0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
8c00: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
8c10: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
8c20: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
8c30: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
8c40: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
8c50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
8c60: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
8c70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c80: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
8c90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8ca0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
8cb0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
8cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
8cd0: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
8ce0: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
8cf0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
8d00: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
8d10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8d20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
8d30: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
8d40: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
8d50: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
8d60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8d70: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
8d80: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
8d90: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
8da0: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
8db0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
8dc0: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
8dd0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
8de0: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
8df0: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
8e00: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
8e10: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
8e20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
8e30: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
8e40: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
8e50: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
8e60: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
8e70: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8e80: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
8e90: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
8ea0: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
8eb0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
8ec0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
8ed0: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
8ee0: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
8ef0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
8f00: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
8f10: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
8f20: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
8f30: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
8f40: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
8f50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8f60: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
8f70: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
8f80: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
8f90: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
8fa0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
8fb0: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
8fc0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
8fd0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
8fe0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8ff0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9000: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9010: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9020: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
9030: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9040: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9050: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9060: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9070: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9080: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9090: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
90a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
90b0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
90c0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
90d0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
90e0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
90f0: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9100: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
9110: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
9120: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
9130: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9140: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9150: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9160: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9170: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9180: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9190: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
91a0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
91b0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
91c0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
91d0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
91e0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
91f0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9200: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
9210: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
9220: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
9230: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9240: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9250: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9260: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9270: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9280: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9290: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
92a0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
92b0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
92c0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
92d0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
92e0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
92f0: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9300: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
9310: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
9320: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
9330: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9340: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9350: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9360: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9370: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9380: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9390: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
93a0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
93b0: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
93c0: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
93d0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
93e0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
93f0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9400: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9410: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9420: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9430: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9440: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9450: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9460: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9470: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9480: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9490: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
94a0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
94b0: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
94c0: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
94d0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
94e0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
94f0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9500: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9510: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9520: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9530: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9540: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9550: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9560: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9570: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9580: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9590: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
95a0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
95b0: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
95c0: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
95d0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
95e0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
95f0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
9600: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
9610: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
9620: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
9630: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9640: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9650: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9660: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9670: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9680: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9690: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
96a0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
96b0: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
96c0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
96d0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
96e0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
96f0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9700: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9710: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
9720: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9730: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9740: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9750: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
9760: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9770: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
9780: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
9790: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
97a0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
97b0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
97c0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
97d0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
97e0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
97f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9800: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9810: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9830: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9840: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9850: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9860: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9870: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
9880: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
9890: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
98a0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
98b0: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
98c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
98d0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
98e0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
98f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
9900: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
9910: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
9920: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
9930: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9940: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9950: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9960: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9970: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
9980: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
9990: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
99a0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
99b0: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
99c0: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
99d0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
99e0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
99f0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9a00: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
9a10: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9a20: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9a30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a40: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
9a50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9a60: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
9a70: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
9a80: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
9a90: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
9aa0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
9ab0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
9ac0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
9ad0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
9ae0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
9af0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
9b00: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
9b10: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
9b20: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
9b30: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
9b40: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
9b50: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
9b60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b70: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
9b80: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b90: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
9ba0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
9bb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
9bc0: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
9bd0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
9be0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
9bf0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
9c00: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
9c10: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
9c20: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
9c30: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
9c40: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
9c50: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
9c60: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
9c70: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
9c80: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
9c90: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
9ca0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
9cb0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
9cc0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9cd0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
9ce0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
9cf0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
9d00: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
9d10: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
9d20: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
9d30: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
9d40: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
9d50: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
9d60: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
9d70: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
9d80: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
9d90: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
9da0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
9db0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
9dc0: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
9dd0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9de0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
9df0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
9e00: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
9e10: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
9e20: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
9e30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9e40: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
9e50: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
9e60: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
9e70: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
9e80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9e90: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
9ea0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
9eb0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
9ec0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9ed0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
9ee0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9ef0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
9f00: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
9f10: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
9f20: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
9f30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
9f40: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9f50: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
9f60: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
9f70: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
9f80: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
9f90: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
9fa0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
9fb0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
9fc0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
9fd0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
9fe0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
9ff0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a000: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a010: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a020: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a030: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a040: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a050: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a060: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a070: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a080: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a090: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a0a0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a0b0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a0c0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a0d0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a0e0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a0f0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
a100: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
a110: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
a120: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
a130: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
a140: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
a150: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
a160: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a170: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a180: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
a190: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
a1a0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
a1b0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
a1c0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
a1d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a1e0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a1f0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a200: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
a210: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
a220: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
a230: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
a240: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
a250: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
a260: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
a270: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
a280: 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74  tatement.  ^If t
a290: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a2b0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
a2c0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
a2d0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
a2e0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
a2f0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a300: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
a310: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
a320: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
a330: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
a340: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
a350: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
a360: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
a370: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
a380: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
a390: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a3a0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a3b0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
a3c0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
a3d0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
a3e0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
a3f0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
a400: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
a410: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a420: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a440: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a450: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a460: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a470: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a480: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a490: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a4a0: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a4b0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a4c0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a4d0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a4e0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a4f0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a500: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a510: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a520: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a530: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a540: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a550: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a560: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a570: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a580: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a590: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a5a0: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a5b0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a5c0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a5d0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a5e0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a5f0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a600: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a610: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a620: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a630: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a640: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a650: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a660: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a670: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a680: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a690: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a6a0: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a6b0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a6c0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
a6d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
a6e0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
a6f0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
a700: 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 66 69 6c   invoke this fil
a710: 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 68 61 76  e-control to hav
a720: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
a730: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
a740: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
a750: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
a760: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
a770: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
a780: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
a790: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
a7a0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
a7b0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
a7c0: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
a7d0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
a7e0: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
a7f0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
a800: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
a810: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
a820: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a830: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a840: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
a850: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
a860: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
a870: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
a880: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
a890: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  y leak..**.** </
a8a0: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
a8b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
a8c0: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
a8d0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
a8e0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
a8f0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a900: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
a910: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
a920: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
a930: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
a940: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
a950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a960: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
a970: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
a980: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
a990: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
a9a0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
a9b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
a9c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a9d0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
a9e0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
a9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
aa00: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
aa10: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
aa20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
aa30: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
aa40: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
aa50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
aa60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
aa70: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
aa80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aa90: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
aaa0: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
aab0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
aac0: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
aad0: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
aae0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
aaf0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
ab00: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
ab10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
ab20: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
ab30: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
ab40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
ab50: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
ab60: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
ab70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ab80: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
ab90: 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41      16../*.** CA
aba0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
abb0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
abc0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
abd0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
abe0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
abf0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
ac00: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
ac10: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
ac20: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
ac30: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
ac40: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
ac50: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ac60: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ac70: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ac80: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ac90: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
aca0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
acb0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
acc0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
acd0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
ace0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
acf0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
ad00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
ad10: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
ad20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
ad30: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
ad40: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
ad50: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
ad60: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
ad70: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ad80: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
ad90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
ada0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
adb0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
adc0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
add0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
ade0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
adf0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
ae00: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
ae10: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
ae20: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
ae30: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
ae40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
ae50: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
ae60: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
ae70: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
ae80: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
ae90: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
aea0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
aeb0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
aec0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
aed0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
aee0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
aef0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
af00: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
af10: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
af20: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
af30: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
af40: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
af50: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
af60: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
af70: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
af80: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
af90: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
afa0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
afb0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
afc0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
afd0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
afe0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
aff0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
b000: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
b010: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
b020: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
b030: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
b040: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
b050: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
b060: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
b070: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b080: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
b090: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
b0a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
b0b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
b0c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b0d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
b0e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
b0f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
b100: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
b110: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
b120: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
b130: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
b140: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
b150: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
b160: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
b170: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
b180: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
b190: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
b1a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
b1b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
b1c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
b1d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
b1e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
b1f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
b200: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
b210: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
b220: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
b230: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
b240: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
b250: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
b260: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
b270: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
b280: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
b290: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
b2a0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
b2b0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
b2c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
b2d0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
b2e0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
b2f0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
b300: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
b310: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
b320: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
b330: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
b340: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
b350: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
b360: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
b370: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
b380: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
b390: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
b3a0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
b3b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
b3c0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
b3d0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
b3e0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b3f0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
b400: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
b410: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
b420: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
b430: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
b440: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
b450: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
b460: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
b470: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
b480: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
b490: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
b4a0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
b4b0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
b4c0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
b4d0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
b4e0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
b4f0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
b500: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
b510: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
b520: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
b530: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
b540: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
b550: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
b560: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
b570: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
b580: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b590: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
b5a0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
b5b0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
b5c0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
b5d0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
b5e0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
b5f0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
b600: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
b610: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
b620: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
b630: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
b640: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
b650: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
b660: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b670: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
b680: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
b690: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
b6a0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
b6b0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
b6c0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
b6d0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
b6e0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
b6f0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
b700: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
b710: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
b720: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
b730: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b740: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
b750: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
b760: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
b770: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
b780: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
b790: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
b7a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
b7b0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
b7c0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
b7d0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
b7e0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
b7f0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b800: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b810: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b820: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b830: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b840: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b850: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b860: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b870: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b880: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b890: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b8a0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b8b0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b8c0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b8d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b8e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b8f0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b900: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b910: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b920: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b930: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
b940: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b950: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
b960: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b970: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
b980: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b990: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
b9a0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b9b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
b9c0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
b9d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b9e0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
b9f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
ba00: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
ba10: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
ba20: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
ba30: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
ba40: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
ba50: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
ba60: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ba70: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
ba80: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ba90: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
baa0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
bab0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
bac0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
bad0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
bae0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
baf0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
bb00: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
bb10: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
bb20: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
bb30: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
bb40: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
bb50: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
bb60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
bb70: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
bb80: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
bb90: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
bba0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
bbb0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
bbc0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
bbd0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
bbe0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
bbf0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
bc00: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
bc10: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
bc20: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
bc30: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
bc40: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
bc50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
bc60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
bc70: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
bc80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bc90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
bca0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
bcb0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
bcc0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
bcd0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
bce0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
bcf0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
bd00: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
bd10: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bd20: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
bd30: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
bd40: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
bd50: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
bd60: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
bd70: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
bd80: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
bd90: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
bda0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
bdb0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
bdc0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
bdd0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
bde0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
bdf0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
be00: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
be10: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
be20: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
be30: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
be40: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
be50: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
be60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
be70: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
be80: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
be90: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
bea0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
beb0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
bec0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
bed0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
bee0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
bef0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
bf00: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
bf10: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
bf20: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
bf30: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
bf40: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
bf50: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
bf60: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
bf70: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
bf80: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
bf90: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
bfa0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
bfb0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
bfc0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
bfd0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
bfe0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
bff0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
c000: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c010: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
c020: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
c030: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
c040: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
c050: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
c060: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
c070: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
c080: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
c090: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
c0a0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
c0b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c0c0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
c0d0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
c0e0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
c0f0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
c100: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
c110: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
c120: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c130: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
c140: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
c150: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
c160: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
c170: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
c180: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
c190: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
c1a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c1b0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
c1c0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c1d0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
c1e0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
c1f0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
c200: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
c210: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
c220: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
c230: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
c240: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
c250: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
c260: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
c270: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
c280: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
c290: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
c2a0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
c2b0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
c2c0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
c2d0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
c2e0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
c2f0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
c300: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
c310: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
c320: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
c330: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
c340: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
c350: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
c360: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
c370: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
c380: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
c390: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
c3a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
c3b0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
c3c0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
c3d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
c3e0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
c3f0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
c400: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
c410: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
c420: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
c430: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
c440: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
c450: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
c460: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
c470: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
c480: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
c490: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
c4a0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
c4b0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
c4c0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
c4d0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
c4e0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
c4f0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
c500: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
c510: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
c520: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
c530: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
c540: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
c550: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
c560: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
c570: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
c580: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
c590: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
c5a0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
c5b0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
c5c0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
c5d0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
c5e0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c5f0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
c600: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
c610: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
c620: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
c630: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
c640: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
c650: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
c660: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
c670: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
c680: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
c690: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
c6a0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
c6b0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
c6c0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
c6d0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
c6e0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
c6f0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c700: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
c710: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
c720: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
c730: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
c740: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
c750: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
c760: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
c770: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
c780: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
c790: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
c7a0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c7b0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
c7c0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
c7d0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
c7e0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
c7f0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c800: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c810: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c820: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c830: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c840: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c850: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c860: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c870: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c880: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c890: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c8a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c8b0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c8c0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c8d0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c8e0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c8f0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c900: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c910: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c920: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c930: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
c940: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
c950: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
c960: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
c970: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
c980: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
c990: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
c9a0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
c9b0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
c9c0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
c9d0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
c9e0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
c9f0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
ca00: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
ca10: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
ca20: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
ca30: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
ca40: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
ca50: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
ca60: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
ca70: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
ca80: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
ca90: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
caa0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
cab0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
cac0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
cad0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
cae0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
caf0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
cb00: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
cb10: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
cb20: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
cb30: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
cb40: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
cb50: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
cb60: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
cb70: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
cb80: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
cb90: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
cba0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
cbb0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
cbc0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
cbd0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
cbe0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
cbf0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
cc00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
cc10: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
cc20: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
cc30: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
cc40: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
cc50: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
cc60: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
cc70: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
cc80: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
cc90: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
cca0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
ccb0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
ccc0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
ccd0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
cce0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
ccf0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
cd00: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
cd10: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
cd20: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
cd30: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
cd40: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
cd50: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
cd60: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
cd70: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
cd80: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
cd90: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
cda0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
cdb0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
cdc0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cdd0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cde0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
cdf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
ce00: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
ce10: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
ce20: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
ce30: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ce40: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
ce50: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
ce60: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
ce70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ce80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
ce90: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
cea0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
ceb0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
cec0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ced0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
cee0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
cef0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
cf00: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
cf10: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cf20: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
cf30: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
cf40: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
cf50: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
cf60: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
cf70: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
cf80: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
cf90: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
cfa0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
cfb0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
cfc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
cfd0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
cfe0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
cff0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d000: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
d010: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
d020: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d030: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
d040: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
d050: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
d060: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
d070: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
d080: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
d090: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
d0a0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
d0b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
d0c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
d0d0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d0e0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
d0f0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
d100: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
d110: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
d120: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
d130: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
d140: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
d150: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
d160: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
d170: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d180: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d190: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
d1a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d1b0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d1c0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
d1d0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
d1e0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
d1f0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
d200: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
d210: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d220: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d230: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
d240: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
d250: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
d260: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d270: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d280: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
d290: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
d2a0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
d2b0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d2c0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
d2d0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
d2e0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
d2f0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
d300: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
d310: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
d320: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
d330: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
d340: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
d350: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
d360: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
d370: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
d380: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
d390: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
d3a0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
d3b0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
d3c0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
d3d0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
d3e0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
d3f0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
d400: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
d410: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
d420: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
d430: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
d440: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
d450: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
d460: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
d470: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d480: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
d490: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d4a0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
d4b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d4c0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
d4d0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
d4e0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
d4f0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d500: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
d510: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d520: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d530: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
d540: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
d550: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d560: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
d570: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
d580: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
d590: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
d5a0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
d5b0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
d5c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
d5d0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
d5e0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
d5f0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
d600: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
d610: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
d620: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
d630: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
d640: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
d650: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
d660: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d670: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
d680: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d690: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d6a0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
d6b0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
d6c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d6d0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
d6e0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
d6f0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
d700: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
d710: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
d720: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
d730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d740: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
d750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d760: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
d770: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
d780: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
d790: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
d7a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d7b0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
d7c0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
d7d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d7e0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
d7f0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d800: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d810: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d820: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d830: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d840: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d850: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d860: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d870: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d880: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d890: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d8a0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d8b0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d8c0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d8d0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d8e0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d8f0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d900: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d910: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d920: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d930: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
d940: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d950: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
d960: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
d970: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
d980: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
d990: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
d9a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
d9b0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
d9c0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
d9d0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
d9e0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
d9f0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
da00: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
da10: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
da20: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
da30: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
da40: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
da50: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
da60: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
da70: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
da80: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
da90: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
daa0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
dab0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
dac0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
dad0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
dae0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
daf0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
db00: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
db10: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
db20: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
db30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
db40: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
db50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
db60: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
db70: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
db80: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
db90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
dba0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
dbb0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
dbc0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
dbd0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
dbe0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
dbf0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
dc00: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
dc10: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
dc20: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
dc30: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
dc40: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
dc50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
dc60: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
dc70: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
dc80: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
dc90: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
dca0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
dcb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dcc0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
dcd0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
dce0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
dcf0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
dd00: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
dd10: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
dd20: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
dd30: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
dd40: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
dd50: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
dd60: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
dd70: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
dd80: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
dd90: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
dda0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
ddb0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
ddc0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
ddd0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
dde0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
ddf0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
de00: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
de10: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
de20: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
de30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
de40: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
de50: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
de60: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
de70: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
de80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
de90: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
dea0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
deb0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
dec0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ded0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
dee0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
def0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
df00: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
df10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
df20: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
df30: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
df40: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
df50: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
df60: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
df70: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
df80: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
df90: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
dfa0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
dfb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
dfc0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
dfd0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
dfe0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
dff0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
e000: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
e010: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
e020: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
e030: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
e040: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
e050: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e060: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
e070: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
e080: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
e090: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
e0a0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
e0b0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
e0c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e0d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e0e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
e0f0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
e100: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
e110: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
e120: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e130: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
e140: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
e150: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
e160: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
e170: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
e180: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
e190: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
e1a0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
e1b0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
e1c0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
e1d0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
e1e0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
e1f0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
e200: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
e210: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
e220: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
e230: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
e240: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
e250: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
e260: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
e270: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
e280: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
e290: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e2a0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e2b0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
e2c0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
e2d0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
e2e0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
e2f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e300: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
e310: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
e320: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
e330: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
e340: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
e350: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
e360: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
e370: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
e380: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
e390: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
e3a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
e3b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e3c0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
e3d0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
e3e0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
e3f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
e400: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
e410: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
e420: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
e430: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
e440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e450: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
e460: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
e470: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
e480: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
e490: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
e4a0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
e4b0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
e4c0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
e4d0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
e4e0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
e4f0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
e500: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
e510: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
e520: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
e530: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e540: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e550: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
e560: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e570: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
e580: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
e590: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
e5a0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
e5b0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
e5c0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
e5d0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
e5e0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e5f0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
e600: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
e610: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
e620: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
e630: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
e640: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
e650: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
e660: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
e670: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e680: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
e690: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
e6a0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
e6b0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
e6c0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
e6d0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
e6e0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
e6f0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
e700: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
e710: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
e720: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e730: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
e740: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
e750: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
e760: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
e770: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
e780: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e7a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
e7b0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
e7c0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
e7d0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
e7e0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
e7f0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e800: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e810: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e820: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e830: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e840: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e850: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e860: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e870: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e880: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e890: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e8a0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e8b0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e8c0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e8d0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e8e0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e8f0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e900: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e910: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e920: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e930: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e940: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
e950: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e960: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
e970: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
e980: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
e990: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
e9a0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
e9b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
e9c0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
e9d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e9e0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
e9f0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
ea00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ea10: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
ea20: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
ea30: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
ea40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ea50: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
ea60: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
ea70: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
ea80: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
ea90: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
eaa0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
eab0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
eac0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
ead0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
eae0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
eaf0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
eb00: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
eb10: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
eb20: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
eb30: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
eb40: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
eb50: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
eb60: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
eb70: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
eb80: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
eb90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
eba0: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
ebb0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ebc0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
ebd0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ebe0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
ebf0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
ec00: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
ec10: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
ec20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
ec30: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
ec40: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
ec50: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
ec60: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
ec70: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
ec80: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
ec90: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
eca0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecb0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
ecc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
ecd0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
ece0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
ecf0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
ed00: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
ed10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
ed20: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
ed30: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
ed40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ed50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ed60: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
ed70: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
ed80: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
ed90: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
eda0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
edb0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
edc0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
edd0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
ede0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
edf0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
ee00: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
ee10: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
ee20: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
ee30: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
ee40: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
ee50: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
ee60: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
ee70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
ee80: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
ee90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
eea0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
eeb0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
eec0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
eed0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
eee0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
eef0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
ef00: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
ef10: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
ef20: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
ef30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ef40: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
ef50: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
ef60: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
ef70: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
ef80: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
ef90: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
efa0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
efb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
efc0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
efd0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
efe0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
eff0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
f000: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
f010: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
f020: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
f030: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
f040: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f050: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
f060: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
f070: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
f080: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
f090: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
f0a0: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
f0b0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
f0c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
f0d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
f0e0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
f0f0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
f100: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f110: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
f120: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
f130: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
f140: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
f150: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
f160: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
f170: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
f180: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
f190: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
f1a0: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
f1b0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
f1c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f1d0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
f1e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
f1f0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
f200: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f210: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
f220: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
f230: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
f240: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
f250: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
f260: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
f270: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
f280: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
f290: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f2a0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
f2b0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
f2c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
f2d0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
f2e0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f2f0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
f300: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
f310: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
f320: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f330: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
f340: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
f350: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
f360: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f370: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
f380: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
f390: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f3a0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
f3b0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
f3c0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
f3d0: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
f3e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
f3f0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
f400: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
f410: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
f420: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f430: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
f440: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
f450: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
f460: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
f470: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
f480: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
f490: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
f4a0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
f4b0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
f4c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f4d0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
f4e0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
f4f0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
f500: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f510: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
f520: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
f530: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
f540: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
f550: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
f560: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
f570: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
f580: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
f590: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
f5a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
f5b0: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
f5c0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
f5d0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
f5e0: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
f5f0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
f600: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
f610: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
f620: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
f630: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
f640: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
f650: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
f660: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
f670: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
f680: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
f690: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
f6a0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
f6b0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
f6c0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f6d0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
f6e0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
f6f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
f700: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
f710: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
f720: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f730: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
f740: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f750: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
f760: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
f770: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
f780: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
f790: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
f7a0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
f7b0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
f7c0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
f7d0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
f7e0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
f7f0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
f800: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
f810: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
f820: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
f830: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
f840: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
f850: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
f860: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
f870: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
f880: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
f890: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
f8a0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
f8b0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
f8c0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
f8d0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
f8e0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
f8f0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
f900: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
f910: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
f920: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
f930: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
f940: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
f950: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
f960: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
f970: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
f980: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
f990: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
f9a0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
f9b0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f9c0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f9d0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
f9e0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
f9f0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
fa00: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
fa10: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
fa20: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
fa30: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
fa40: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
fa50: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
fa60: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
fa70: 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
fa80: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
fa90: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
faa0: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
fab0: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
fac0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
fad0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
fae0: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
faf0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
fb00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fb10: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
fb20: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
fb30: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
fb40: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
fb50: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
fb60: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
fb70: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
fb80: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
fb90: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
fba0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
fbb0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
fbc0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
fbd0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
fbe0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
fbf0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
fc00: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
fc10: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
fc20: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
fc30: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
fc40: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
fc50: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
fc60: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
fc70: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
fc80: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
fc90: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
fca0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
fcb0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
fcc0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
fcd0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
fce0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
fcf0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
fd00: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
fd10: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
fd20: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
fd30: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
fd40: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
fd50: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
fd60: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
fd70: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
fd80: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
fd90: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
fda0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
fdb0: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
fdc0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
fdd0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
fde0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
fdf0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
fe00: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
fe10: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
fe20: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
fe30: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
fe40: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
fe50: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
fe60: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
fe70: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
fe80: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
fe90: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
fea0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
feb0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
fec0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
fed0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
fee0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
fef0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
ff00: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
ff10: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
ff20: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
ff30: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
ff40: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
ff50: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
ff60: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
ff70: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
ff80: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
ff90: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
ffa0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
ffb0: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
ffc0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
ffd0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
ffe0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
fff0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
10000 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
10010 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
10020 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
10030 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
10040 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10050 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
10060 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
10070 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
10080 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
10090 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
100a0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
100b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
100c0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
100d0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
100e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
100f0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
10100 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10110 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
10120 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
10130 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
10140 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
10150 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
10160 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
10170 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
10180 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10190 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
101a0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
101b0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
101c0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
101d0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
101e0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
101f0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
10200 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
10210 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
10220 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
10230 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
10240 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
10250 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
10260 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
10270 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10280 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
10290 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
102a0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
102b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
102c0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
102d0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
102e0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
102f0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
10300 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
10310 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
10320 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
10330 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
10340 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
10350 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
10360 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
10370 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
10380 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
10390 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
103a0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
103b0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
103c0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
103d0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
103e0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
103f0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
10400 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
10410 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
10420 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
10430 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
10440 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
10450 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10460 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
10470 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
10480 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
10490 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
104a0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
104b0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
104c0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
104d0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
104e0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
104f0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
10500 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
10510 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
10520 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
10530 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
10540 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
10550 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
10560 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
10570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10580 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
10590 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
105a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
105b0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
105c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
105d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
105e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
105f0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
10600 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
10610 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
10620 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
10630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10640 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
10650 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
10660 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
10670 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
10680 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
10690 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
106a0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
106b0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
106c0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
106d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
106e0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
106f0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
10700 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
10710 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
10720 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
10730 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10740 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
10750 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
10760 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10770 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
10780 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10790 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
107a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
107b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
107c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
107d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
107e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
107f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
10800 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
10810 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
10820 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
10830 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
10840 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
10850 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
10860 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
10870 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
10880 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
10890 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
108a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
108b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
108c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
108d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
108e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
108f0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10900 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
10910 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
10920 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
10930 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
10940 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
10950 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
10960 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10970 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
10980 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10990 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
109a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
109b0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
109c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
109d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
109e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
109f0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
10a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10a10 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
10a20 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10a30 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10a40 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10a50 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10a60 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10a70 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
10a80 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
10a90 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
10aa0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
10ab0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
10ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
10ad0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10ae0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
10af0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10b00 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
10b10 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
10b20 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
10b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10b40 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10b50 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
10b60 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
10b70 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
10b80 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
10b90 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
10ba0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
10bb0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
10bc0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
10bd0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
10be0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
10bf0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
10c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10c10 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
10c20 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
10c30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10c40 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10c50 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10c60 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10c70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10c80 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10c90 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10ca0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
10cb0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
10cc0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
10cd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ce0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
10cf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10d00 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10d10 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
10d20 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
10d30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10d40 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10d50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10d60 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
10d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10d80 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
10d90 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
10da0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
10db0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
10dc0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
10dd0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
10de0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
10df0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
10e00 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
10e10 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
10e20 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
10e30 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
10e40 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
10e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10e60 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
10e70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
10e80 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
10e90 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
10ea0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
10eb0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
10ec0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
10ed0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10ee0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
10ef0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
10f00 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
10f10 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
10f20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10f30 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
10f40 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
10f50 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
10f60 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
10f70 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
10f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10f90 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
10fa0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
10fb0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
10fc0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
10fd0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
10fe0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
10ff0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11000 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11010 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11020 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11040 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11050 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11060 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
11070 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
11080 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
11090 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
110a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
110b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
110c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
110d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
110e0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
110f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11100 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11110 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11120 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11130 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
11140 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11150 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
11160 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
11170 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
11180 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
11190 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
111a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
111b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
111c0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
111d0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
111e0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
111f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11200 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
11210 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
11220 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
11230 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11240 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
11250 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
11260 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
11270 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
11280 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
11290 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
112a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
112b0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
112c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
112d0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
112e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
112f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11300 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
11310 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
11320 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11330 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11340 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11350 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11360 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11370 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
11380 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11390 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
113a0 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
113b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
113c0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
113d0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
113e0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
113f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11400 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
11410 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
11420 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
11430 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
11440 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
11450 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
11460 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
11470 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
11480 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11490 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
114a0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
114b0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
114c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
114d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
114e0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
114f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11500 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
11510 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
11520 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
11530 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11540 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
11550 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
11560 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
11570 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
11580 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
11590 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
115a0 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
115b0 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
115c0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
115d0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
115e0 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
115f0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
11600 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
11610 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
11620 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
11630 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
11640 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
11650 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11660 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
11670 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11680 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
11690 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
116a0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
116b0 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
116c0 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
116d0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
116e0 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
116f0 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
11700 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
11710 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
11720 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
11730 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
11740 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
11750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
11760 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
11770 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
11780 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
11790 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
117a0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
117b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
117c0 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
117d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
117e0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
117f0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11800 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
11810 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
11820 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
11830 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11840 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
11850 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
11860 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
11870 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
11880 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
11890 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
118a0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
118b0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
118c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
118d0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
118e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
118f0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11900 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
11910 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
11920 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
11930 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
11940 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11950 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
11960 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
11970 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
11980 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11990 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
119a0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
119b0 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
119c0 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
119d0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
119e0 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
119f0 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
11a00 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
11a10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
11a20 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
11a30 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
11a40 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
11a50 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
11a60 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
11a70 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
11a80 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
11a90 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
11aa0 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
11ab0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
11ac0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
11ad0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
11ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11af0 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
11b00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11b10 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
11b20 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
11b30 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
11b40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11b50 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11b60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11b70 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
11b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11b90 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
11ba0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
11bb0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
11bc0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
11bd0 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
11be0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
11bf0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
11c00 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
11c10 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
11c20 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
11c30 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
11c40 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
11c50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
11c60 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
11c70 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
11c80 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
11c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11ca0 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
11cb0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11cc0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11cd0 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
11ce0 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
11cf0 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
11d00 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
11d10 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
11d20 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
11d30 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
11d40 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
11d50 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
11d60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
11d70 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
11d80 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
11d90 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
11da0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
11db0 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
11dc0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
11dd0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
11de0 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
11df0 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
11e00 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
11e10 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
11e20 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
11e30 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
11e40 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
11e50 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
11e60 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
11e70 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
11e80 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
11e90 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
11ea0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
11eb0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
11ec0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
11ed0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
11ee0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
11ef0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
11f00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11f10 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
11f20 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
11f30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
11f40 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
11f50 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
11f60 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
11f70 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
11f80 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
11f90 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
11fa0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
11fb0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
11fc0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
11fd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
11fe0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
11ff0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
12000 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
12010 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12020 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
12030 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
12040 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
12050 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
12060 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
12070 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
12080 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
12090 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
120a0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
120c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
120d0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
120e0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
120f0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12100 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
12110 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
12120 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
12130 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
12140 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
12150 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
12160 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12170 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
12180 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12190 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
121a0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
121b0 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
121c0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
121d0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
121e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
121f0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
12200 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
12210 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12220 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
12230 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
12240 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
12250 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
12260 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
12270 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
12280 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
12290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
122a0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
122b0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
122c0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
122d0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
122e0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
122f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
12300 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
12310 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
12320 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
12330 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
12340 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
12350 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
12360 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
12370 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
12380 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
12390 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
123a0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
123b0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
123c0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
123d0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
123e0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
123f0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
12400 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
12410 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
12420 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
12430 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
12440 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
12450 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
12460 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
12470 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12480 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
12490 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
124a0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
124b0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
124c0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
124d0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
124e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
124f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12500 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
12510 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
12520 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12530 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12540 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12550 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12560 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12570 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12580 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12590 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
125a0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
125b0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
125c0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
125d0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
125e0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
125f0 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
12600 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
12610 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
12620 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
12630 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
12640 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
12650 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
12660 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
12670 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
12680 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12690 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
126a0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
126b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
126c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
126d0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
126e0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
126f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12700 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
12710 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
12720 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
12730 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
12740 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
12750 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
12760 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
12770 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12780 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
12790 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
127a0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
127b0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
127c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
127d0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
127e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
127f0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
12800 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12810 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12820 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12830 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12840 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12850 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12860 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12870 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12880 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
12890 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
128a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
128b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
128c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
128d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
128e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
128f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
12900 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
12910 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
12920 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
12930 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
12940 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
12950 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
12960 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
12970 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
12980 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
12990 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
129a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
129b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
129c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
129d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
129e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
129f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
12a00 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
12a10 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
12a20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
12a30 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
12a40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
12a50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12a60 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12a70 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
12a80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12a90 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
12aa0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12ab0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12ad0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
12ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
12af0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
12b00 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12b10 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12b20 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
12b30 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
12b40 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12b50 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
12b60 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
12b70 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
12b80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12b90 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
12ba0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
12bb0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
12bc0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
12bd0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
12be0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
12bf0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
12c00 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
12c10 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
12c20 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
12c30 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12c40 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
12c50 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
12c60 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
12c70 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12c80 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
12c90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
12ca0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
12cb0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
12cc0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
12cd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
12ce0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
12cf0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
12d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12d10 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
12d20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12d30 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
12d40 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12d50 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12d60 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12d70 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12d80 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
12d90 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
12da0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
12db0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
12dc0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
12dd0 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
12de0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
12df0 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
12e00 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12e10 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
12e20 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
12e30 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
12e40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
12e50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12e70 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
12e80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12e90 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
12ea0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12eb0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12ec0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12ed0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12ee0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
12ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
12f00 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
12f10 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
12f20 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
12f30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12f40 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
12f50 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
12f60 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f70 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
12f80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
12f90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
12fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
12fb0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
12fc0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
12fd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
12fe0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
12ff0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13000 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
13010 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
13020 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
13030 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
13040 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
13050 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13060 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13070 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13080 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13090 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
130a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
130b0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
130c0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
130d0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
130e0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
130f0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13100 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13110 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13120 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13140 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
13150 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
13160 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13180 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13190 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
131a0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
131b0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
131c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
131d0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
131e0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
131f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
13200 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13210 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
13220 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
13230 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
13240 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
13250 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
13260 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
13270 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
13280 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
13290 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
132a0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
132b0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
132c0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
132d0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
132e0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
132f0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
13300 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
13310 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
13320 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13330 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
13340 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13350 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
13360 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
13370 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
13380 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
13390 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
133a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
133b0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
133c0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
133d0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
133e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
133f0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
13400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
13410 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
13420 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13430 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13440 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
13450 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
13460 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13470 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13480 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
13490 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
134a0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
134b0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
134c0 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
134d0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
134e0 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
134f0 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
13500 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
13510 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
13520 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
13530 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
13540 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
13550 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
13560 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
13570 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
13580 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
13590 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
135a0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
135b0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
135c0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
135d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
135e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
135f0 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
13600 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
13610 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
13620 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
13630 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
13640 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
13650 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13660 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
13670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
13680 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
13690 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
136a0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
136b0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
136c0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
136d0 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
136e0 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
136f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
13700 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
13710 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
13720 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
13730 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
13740 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13750 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
13760 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54  X_SCAN.** <dd> T
13770 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13780 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
13790 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
137a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
137b0 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
137c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
137d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
137e0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
137f0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
13800 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
13810 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
13820 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64  ptimizer.  The d
13830 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
13840 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
13850 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
13860 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
13870 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
13880 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
13890 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
138a0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
138b0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
138c0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
138d0 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
138e0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
138f0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
13900 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
13910 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
13920 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
13930 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
13940 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
13950 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61  alfunction.** ma
13960 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74  lfunction when t
13970 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
13980 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
13990 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
139a0 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
139b0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
139c0 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
139d0 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
139e0 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
139f0 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
13a00 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
13a10 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
13a20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
13a30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13a40 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
13a50 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13a60 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
13a70 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
13a80 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
13a90 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
13aa0 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
13ab0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
13ac0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
13ad0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
13ae0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
13af0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
13b00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
13b10 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
13b20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
13b30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13b40 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
13b50 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
13b60 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
13b70 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
13b80 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
13b90 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
13ba0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
13bb0 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
13bc0 5f 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63  _SQLLOG pre-proc
13bd0 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
13be0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
13bf0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
13c00 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
13c10 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
13c20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
13c30 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
13c40 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
13c50 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
13c60 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
13c70 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
13c80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
13c90 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
13ca0 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
13cb0 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
13cc0 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
13cd0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
13ce0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
13cf0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
13d00 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
13d10 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
13d20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
13d30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
13d40 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
13d50 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
13d60 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
13d70 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
13d80 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
13d90 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
13da0 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
13db0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
13dc0 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
13dd0 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
13de0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
13df0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13e00 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
13e10 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
13e20 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
13e30 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
13e40 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
13e50 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
13e60 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
13e70 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
13e80 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
13e90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
13ea0 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
13eb0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
13ec0 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
13ed0 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
13ee0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
13ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13f00 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
13f10 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
13f20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13f30 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
13f40 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
13f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13f60 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
13f70 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
13f80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13f90 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
13fa0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
13fb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
13fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13fd0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13fe0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
13ff0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
14000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14010 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14020 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
14030 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
14040 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
14050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14060 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
14070 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
14080 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
14090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
140a0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
140b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
140c0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
140d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
140e0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
140f0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
14100 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14110 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
14120 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
14130 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14140 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14160 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
14170 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14180 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
14190 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
141a0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
141b0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
141c0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
141d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
141e0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
141f0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
14200 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14210 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14220 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
14230 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14250 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
14260 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
14270 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14280 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
14290 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
142a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
142b0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
142c0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
142d0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
142e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
142f0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
14300 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14310 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
14320 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14330 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
14340 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
14350 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
14360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14370 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
14380 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
14390 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
143a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
143b0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
143c0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
143d0 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
143e0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
143f0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
14400 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
14410 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
14420 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
14430 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14450 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14460 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14470 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14480 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
14490 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
144a0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
144b0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
144c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
144d0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
144e0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
144f0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
14500 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
14510 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
14520 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
14530 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
14540 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
14550 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
14560 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
14570 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
14580 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
14590 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
145a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
145b0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
145c0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
145d0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
145e0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
145f0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
14600 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
14610 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14620 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
14630 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
14640 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
14650 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14660 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
14670 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
14680 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
14690 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
146a0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
146b0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
146c0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
146d0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
146e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
146f0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
14700 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
14710 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
14720 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
14730 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
14740 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14750 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
14760 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
14770 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
14780 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
14790 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
147a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
147b0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
147c0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
147d0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
147e0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
147f0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
14800 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
14810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
14820 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
14830 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
14840 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14850 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14860 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
14870 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
14880 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14890 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
148a0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
148b0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
148c0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
148d0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
148e0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
148f0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
14900 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
14910 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
14920 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
14930 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
14940 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
14950 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
14960 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
14970 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
14980 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
14990 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
149a0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
149b0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
149c0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
149d0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
149e0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
149f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
14a00 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14a10 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
14a20 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
14a30 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
14a40 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
14a50 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
14a60 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
14a70 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
14a80 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
14a90 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
14aa0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
14ab0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
14ac0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
14ad0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
14ae0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
14af0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
14b00 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
14b10 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
14b20 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
14b30 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
14b40 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
14b50 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
14b60 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
14b70 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
14b80 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
14b90 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
14ba0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
14bb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
14bc0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
14bd0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
14be0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
14bf0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
14c00 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
14c10 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
14c20 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
14c30 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
14c40 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
14c50 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
14c60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14c70 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
14c80 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
14c90 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
14ca0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
14cb0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
14cc0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
14cd0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
14ce0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
14cf0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
14d00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14d10 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
14d20 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
14d30 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
14d40 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
14d50 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
14d60 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
14d70 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
14d80 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
14d90 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
14da0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
14db0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
14dc0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
14dd0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
14de0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
14df0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
14e00 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
14e10 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
14e20 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
14e30 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
14e40 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
14e50 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
14e60 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
14e70 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
14e80 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
14e90 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
14ea0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
14eb0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
14ec0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
14ed0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
14ee0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
14ef0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
14f00 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
14f10 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
14f20 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
14f30 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
14f40 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
14f50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
14f60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14f70 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
14f80 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
14f90 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
14fa0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
14fb0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
14fc0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
14fd0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
14fe0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
14ff0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15000 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15010 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15020 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
15030 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
15040 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
15050 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
15060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15070 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15080 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
15090 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
150a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
150b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
150c0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
150d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
150e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
150f0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
15100 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
15110 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
15120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
15130 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
15140 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
15150 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
15160 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
15170 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
15180 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
15190 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
151a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
151b0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
151c0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
151d0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
151e0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
151f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15200 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
15210 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
15220 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
15230 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
15240 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
15250 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
15260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
15270 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
15280 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
15290 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
152a0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
152b0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
152c0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
152d0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
152e0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
152f0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
15300 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
15310 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
15320 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
15330 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
15340 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
15350 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
15360 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
15370 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
15380 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
15390 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
153a0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
153b0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
153c0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
153d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
153e0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
153f0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
15400 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15410 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15420 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
15430 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
15440 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15450 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
15460 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
15470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15480 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
15490 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
154a0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
154b0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
154c0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
154d0 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
154e0 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
154f0 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
15500 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
15510 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
15520 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
15530 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
15540 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
15550 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
15560 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
15570 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
15580 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
15590 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
155a0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
155b0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
155c0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
155d0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
155e0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
155f0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
15600 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
15610 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
15620 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
15630 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
15640 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
15650 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
15660 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
15670 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
15680 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
15690 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
156a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
156b0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
156c0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
156d0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
156e0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
156f0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
15700 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
15710 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
15720 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
15730 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
15740 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
15750 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
15760 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
15770 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
15780 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
15790 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
157a0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
157b0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
157c0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
157d0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
157e0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
157f0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
15800 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
15810 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
15820 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
15830 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
15840 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
15850 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
15860 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
15870 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
15880 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
15890 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
158a0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
158b0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
158c0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
158d0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
158e0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
158f0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
15900 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
15910 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
15920 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
15930 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
15940 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
15950 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
15960 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
15970 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
15980 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
15990 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
159a0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
159b0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
159c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
159d0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
159e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
159f0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
15a00 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
15a10 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
15a20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
15a30 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
15a40 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
15a50 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
15a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15a70 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
15a80 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
15a90 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
15aa0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
15ab0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
15ac0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
15ad0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
15ae0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
15af0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
15b00 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
15b10 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
15b20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15b30 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
15b40 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
15b50 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
15b60 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
15b70 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
15b80 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
15b90 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
15ba0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
15bb0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
15bc0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
15bd0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
15be0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
15bf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
15c00 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
15c10 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
15c20 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
15c30 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
15c40 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
15c50 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
15c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
15c70 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
15c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
15c90 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
15ca0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
15cb0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
15cc0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
15cd0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
15ce0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
15cf0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
15d00 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
15d10 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
15d20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
15d30 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
15d40 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
15d50 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
15d60 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
15d70 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
15d80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
15d90 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
15da0 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
15db0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
15dc0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
15dd0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
15de0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
15df0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
15e00 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
15e10 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
15e20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
15e30 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
15e40 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
15e50 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
15e60 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
15e70 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
15e80 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
15e90 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
15ea0 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
15eb0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
15ec0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
15ed0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
15ee0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
15ef0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
15f00 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
15f10 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
15f20 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
15f30 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
15f40 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
15f50 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
15f60 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
15f70 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
15f80 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
15f90 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
15fa0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
15fb0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
15fc0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
15fd0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
15fe0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
15ff0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
16000 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
16010 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
16020 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16030 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
16040 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
16050 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
16060 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
16070 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
16080 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
16090 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
160a0 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
160b0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
160c0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
160d0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
160e0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
160f0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
16100 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
16110 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
16120 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
16130 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
16140 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
16150 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
16160 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
16170 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
16180 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
16190 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
161a0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
161b0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
161c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
161d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
161e0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
161f0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
16200 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
16210 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
16220 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
16230 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
16240 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
16250 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
16260 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
16270 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
16280 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
16290 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
162a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
162b0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
162c0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
162d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
162e0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
162f0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
16300 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
16310 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
16320 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
16330 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
16340 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
16350 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
16360 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
16370 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
16380 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
16390 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
163a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
163b0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
163c0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
163d0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
163e0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
163f0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
16400 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
16410 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
16420 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
16430 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
16440 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
16450 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
16460 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
16470 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
16480 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
16490 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
164a0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
164b0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
164c0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
164d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
164e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
164f0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
16500 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
16510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16520 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
16530 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
16540 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
16550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16560 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
16570 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
16580 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
16590 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
165a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
165b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
165c0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
165d0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
165e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
165f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16600 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
16610 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
16620 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
16630 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
16640 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
16650 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16660 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
16670 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
16680 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
16690 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
166a0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
166b0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
166c0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
166d0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
166e0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
166f0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
16700 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16710 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
16720 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
16730 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16740 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
16750 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
16760 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
16770 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
16780 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
16790 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
167a0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
167b0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
167c0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
167d0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
167e0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
167f0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
16800 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
16810 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
16820 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
16830 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
16840 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
16850 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
16860 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
16870 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16880 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
16890 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
168a0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
168b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
168c0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
168d0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
168e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
168f0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
16900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
16910 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
16920 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
16930 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
16940 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
16950 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
16960 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
16970 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
16980 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
16990 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
169a0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
169b0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
169c0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
169d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
169e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
169f0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
16a00 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16a10 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
16a20 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
16a30 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
16a40 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
16a50 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
16a60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
16a70 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
16a80 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16a90 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
16aa0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
16ab0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
16ac0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
16ad0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
16ae0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
16af0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
16b00 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
16b10 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
16b20 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
16b30 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
16b40 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
16b50 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
16b60 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
16b70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
16b80 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
16b90 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
16ba0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
16bb0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
16bc0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
16bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
16be0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
16bf0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
16c00 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
16c10 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
16c20 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
16c30 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
16c40 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
16c50 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
16c60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
16c70 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
16c80 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
16c90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
16ca0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
16cb0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
16cc0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
16cd0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
16ce0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
16cf0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
16d00 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
16d10 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
16d20 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
16d30 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
16d40 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
16d50 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
16d60 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
16d70 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
16d80 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
16d90 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
16da0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
16db0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
16dc0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
16dd0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
16de0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
16df0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
16e00 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
16e10 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
16e20 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16e30 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
16e40 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
16e50 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
16e60 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
16e70 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
16e80 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
16e90 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
16ea0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
16eb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16ec0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
16ed0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
16ee0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
16ef0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
16f00 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
16f10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
16f20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
16f30 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
16f40 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
16f50 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
16f60 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
16f70 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
16f80 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
16f90 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
16fa0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
16fb0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
16fc0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
16fd0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
16fe0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
16ff0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
17000 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
17010 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17020 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17030 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
17040 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
17050 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
17060 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
17070 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
17080 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
17090 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
170a0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
170b0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
170c0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
170d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
170e0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
170f0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
17100 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
17110 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17120 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17130 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17140 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
17150 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
17160 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17170 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
17180 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
17190 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
171a0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
171b0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
171c0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
171d0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
171e0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
171f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17200 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
17210 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
17220 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
17230 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17240 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
17250 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
17260 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
17270 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
17280 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
17290 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
172a0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
172b0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
172c0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
172d0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
172e0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
172f0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
17300 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
17310 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
17320 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
17330 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
17340 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
17350 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17360 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
17370 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
17380 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
17390 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
173a0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
173b0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
173c0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
173d0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
173e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
173f0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
17400 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
17410 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
17420 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
17430 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
17440 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
17450 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
17460 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
17470 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
17480 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
17490 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
174a0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
174b0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
174c0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
174d0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
174e0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
174f0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
17500 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
17510 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
17520 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
17530 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
17540 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
17550 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
17560 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
17570 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
17580 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
17590 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
175a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
175b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
175c0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
175d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
175e0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
175f0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
17600 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
17610 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
17620 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
17630 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
17640 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
17650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
17660 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
17670 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
17680 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
17690 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
176a0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
176b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
176c0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
176d0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
176e0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
176f0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
17700 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
17710 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
17720 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
17730 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
17740 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
17750 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
17760 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
17770 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
17780 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
17790 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
177a0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
177b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
177c0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
177d0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
177e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
177f0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
17800 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
17810 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
17820 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
17830 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
17840 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
17850 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
17860 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17870 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
17880 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
17890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
178a0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
178b0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
178c0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
178d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
178e0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
178f0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
17900 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
17910 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
17920 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
17930 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
17940 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
17950 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
17960 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
17970 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
17980 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
17990 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
179a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
179b0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
179c0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
179d0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
179e0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
179f0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
17a00 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
17a10 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
17a20 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17a30 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
17a40 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
17a50 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
17a60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17a70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
17a80 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
17a90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
17aa0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
17ab0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
17ac0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
17ad0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17ae0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
17af0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
17b00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17b10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
17b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
17b30 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
17b40 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
17b50 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
17b60 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
17b70 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
17b80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
17b90 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
17ba0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
17bb0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
17bc0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
17bd0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
17be0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
17bf0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17c00 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
17c10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
17c20 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
17c30 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
17c40 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
17c50 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
17c60 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
17c70 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
17c80 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
17c90 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
17ca0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
17cb0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
17cc0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
17cd0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
17ce0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
17cf0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
17d00 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
17d10 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
17d20 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
17d30 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
17d40 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
17d50 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
17d60 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
17d70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
17d80 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
17d90 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
17da0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
17db0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17dc0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
17dd0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
17de0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
17df0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
17e00 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
17e10 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
17e20 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
17e30 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
17e40 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
17e50 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
17e60 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
17e70 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
17e80 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
17e90 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
17ea0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
17eb0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
17ec0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
17ed0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
17ee0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
17ef0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
17f00 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
17f10 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
17f20 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
17f30 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
17f40 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
17f50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17f60 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
17f70 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
17f80 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
17f90 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
17fa0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
17fb0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
17fc0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
17fd0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
17fe0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
17ff0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
18000 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
18010 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
18020 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
18030 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
18040 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18050 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18060 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
18070 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
18080 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
18090 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
180a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
180b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
180c0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
180d0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
180e0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
180f0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
18100 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
18110 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
18120 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
18130 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
18140 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
18150 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
18160 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
18170 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
18180 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
18190 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
181a0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
181b0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
181c0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
181d0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
181e0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
181f0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
18200 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
18210 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
18220 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
18230 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
18240 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
18250 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
18260 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
18270 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
18280 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
18290 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
182a0 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
182b0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
182c0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
182d0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
182e0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
182f0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
18300 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
18310 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
18320 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
18330 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
18340 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
18350 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
18360 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
18370 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
18380 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
18390 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
183a0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
183b0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
183c0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
183d0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
183e0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
183f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
18400 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
18410 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18420 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
18430 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
18440 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
18450 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
18460 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
18470 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
18480 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
18490 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
184a0 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
184b0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
184c0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
184d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
184e0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
184f0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
18500 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
18510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18520 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18530 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
18540 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
18550 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
18560 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
18570 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
18580 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
18590 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
185a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
185b0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
185c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
185d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
185e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
185f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
18600 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
18610 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
18620 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
18630 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
18640 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
18650 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18660 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
18670 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
18680 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
18690 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
186a0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
186b0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
186c0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
186d0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
186e0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
186f0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
18700 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
18710 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
18720 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
18730 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
18740 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
18750 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
18760 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
18770 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
18780 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
18790 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
187a0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
187b0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
187c0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
187d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
187e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
187f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
18800 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
18810 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
18820 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
18830 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
18840 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
18850 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
18860 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
18870 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
18880 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
18890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
188a0 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
188b0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
188c0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
188d0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
188e0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
188f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
18900 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
18910 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
18920 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
18930 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
18940 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
18950 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
18960 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
18970 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
18980 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
18990 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
189a0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
189b0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
189c0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
189d0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
189e0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
189f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
18a00 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
18a10 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
18a20 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
18a30 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
18a40 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
18a50 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
18a60 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
18a70 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
18a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
18a90 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
18aa0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
18ab0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
18ac0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
18ad0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
18ae0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
18af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
18b00 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
18b10 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
18b20 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
18b30 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
18b40 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
18b50 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
18b60 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
18b70 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
18b80 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
18b90 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
18ba0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
18bb0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
18bc0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
18bd0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
18be0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
18bf0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
18c00 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
18c10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
18c20 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
18c30 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
18c40 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
18c50 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
18c60 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
18c70 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
18c80 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
18c90 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
18ca0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
18cb0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
18cc0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
18cd0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
18ce0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
18cf0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
18d00 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
18d10 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
18d20 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
18d30 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
18d40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18d50 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
18d60 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
18d70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
18d80 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
18d90 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18da0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
18db0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
18dc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18dd0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
18de0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
18df0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
18e00 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
18e10 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
18e20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
18e30 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
18e40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18e50 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
18e60 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
18e70 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
18e80 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
18e90 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
18ea0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
18eb0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
18ec0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18ed0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
18ee0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
18ef0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
18f00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18f10 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
18f20 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
18f30 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
18f40 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
18f50 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
18f60 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
18f70 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
18f80 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
18f90 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
18fa0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
18fb0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
18fc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
18fd0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
18fe0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
18ff0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
19000 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
19010 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
19020 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
19030 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
19040 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19050 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19060 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19070 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
19080 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19090 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
190a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
190b0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
190c0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
190d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
190e0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
190f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
19100 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
19110 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19120 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
19130 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19140 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
19150 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19160 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
19170 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
19180 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
19190 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
191a0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
191b0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
191c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
191d0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
191e0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
191f0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
19200 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
19210 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
19220 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
19230 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
19240 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
19250 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
19260 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
19270 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
19280 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
19290 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
192a0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
192b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
192c0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
192d0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
192e0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
192f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
19300 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
19310 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
19320 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
19330 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
19340 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
19350 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
19360 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
19370 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
19380 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
19390 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
193a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
193b0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
193c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
193d0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
193e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
193f0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
19400 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
19410 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
19420 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
19430 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
19440 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
19450 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
19460 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
19470 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
19480 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
19490 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
194a0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
194b0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
194c0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
194d0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
194e0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
194f0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
19500 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
19510 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
19520 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
19530 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
19540 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
19550 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
19560 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
19570 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
19580 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
19590 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
195a0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
195b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
195c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
195d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
195e0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
195f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19600 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
19610 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
19620 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
19630 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
19640 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
19650 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
19660 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
19670 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
19680 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
19690 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
196a0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
196b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
196c0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
196d0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
196e0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
196f0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
19700 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
19710 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
19720 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
19730 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
19740 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
19750 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
19760 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
19770 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
19780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
19790 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
197a0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
197b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
197c0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
197d0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
197e0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
197f0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
19800 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
19810 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
19820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
19830 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
19840 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
19850 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
19860 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
19870 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
19880 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
19890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
198a0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
198b0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
198c0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
198d0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
198e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
198f0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
19900 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
19910 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
19920 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
19930 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
19940 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
19950 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
19960 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
19970 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
19980 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
19990 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
199a0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
199b0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
199c0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
199d0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
199e0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
199f0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
19a00 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
19a10 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
19a20 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
19a30 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
19a40 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
19a50 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
19a60 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
19a70 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
19a80 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
19a90 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
19aa0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
19ab0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
19ac0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
19ad0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
19ae0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
19af0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
19b00 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
19b10 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
19b20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19b30 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
19b40 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
19b50 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
19b60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
19b70 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
19b80 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
19b90 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
19ba0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
19bb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
19bc0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
19bd0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
19be0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
19bf0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
19c00 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
19c10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
19c20 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
19c30 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
19c40 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
19c50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
19c60 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
19c70 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
19c80 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
19c90 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
19ca0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
19cb0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
19cc0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
19cd0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
19ce0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
19cf0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
19d00 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
19d10 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
19d20 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
19d30 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
19d40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
19d50 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
19d60 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
19d70 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
19d80 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
19d90 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
19da0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19db0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
19dc0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
19dd0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
19de0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19df0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
19e00 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
19e10 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
19e20 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
19e30 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
19e40 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
19e50 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
19e60 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
19e70 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
19e80 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
19e90 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
19ea0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
19eb0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
19ec0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
19ed0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
19ee0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
19ef0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
19f00 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
19f10 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
19f20 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
19f30 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
19f40 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
19f50 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
19f60 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
19f70 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
19f80 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
19f90 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
19fa0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
19fb0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
19fc0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
19fd0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
19fe0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
19ff0 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1a000 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1a010 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1a020 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1a030 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1a040 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1a050 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1a060 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a070 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a080 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1a090 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1a0a0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1a0b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a0c0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1a0d0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1a0e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1a0f0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1a100 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1a110 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1a120 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1a130 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1a140 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1a150 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1a160 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1a170 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1a180 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1a190 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1a1a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a1b0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1a1c0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1a1d0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1a1e0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1a1f0 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1a200 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1a210 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1a220 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1a230 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a240 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1a250 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1a260 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1a270 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1a280 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a290 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1a2a0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1a2b0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1a2c0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1a2d0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1a2e0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1a2f0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1a300 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a310 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1a320 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1a330 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1a340 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1a350 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a360 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1a370 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1a380 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1a390 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1a3a0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1a3b0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1a3c0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1a3d0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1a3e0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1a3f0 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1a400 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1a410 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1a420 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1a430 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1a440 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1a450 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1a460 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1a470 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1a480 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1a490 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1a4a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a4b0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1a4c0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1a4d0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1a4e0 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1a4f0 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1a500 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1a510 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a520 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1a530 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1a540 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1a550 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1a560 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1a570 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1a580 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1a590 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1a5a0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1a5b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a5c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1a5d0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1a5e0 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1a5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1a600 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1a610 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1a620 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1a630 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1a640 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1a650 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1a660 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1a670 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1a680 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1a690 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1a6a0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1a6b0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1a6c0 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1a6d0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1a6e0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1a6f0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1a700 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1a710 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1a720 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1a730 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1a740 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1a750 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1a760 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1a770 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1a780 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1a790 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1a7a0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1a7b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a7c0 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1a7d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a7e0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1a7f0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1a800 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1a810 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1a820 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1a830 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1a840 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1a850 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1a860 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1a870 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1a880 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1a890 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1a8a0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1a8b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1a8c0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1a8d0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1a8e0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1a8f0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1a900 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1a910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1a920 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1a930 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1a940 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1a950 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1a960 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1a970 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1a980 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1a990 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1a9a0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1a9b0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1a9c0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1a9d0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1a9e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1a9f0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1aa00 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1aa10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1aa20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1aa30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1aa40 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1aa50 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1aa60 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1aa70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1aa80 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1aa90 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1aaa0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1aab0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1aac0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1aad0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1aae0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1aaf0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1ab00 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1ab10 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1ab20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1ab30 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ab40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ab50 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ab60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ab70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ab80 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ab90 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1aba0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1abb0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1abc0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1abd0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1abe0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1abf0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1ac00 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1ac10 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1ac20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1ac30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ac40 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1ac50 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ac60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ac70 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ac80 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ac90 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1aca0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1acb0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1acc0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1acd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1ace0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1acf0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1ad00 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1ad10 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1ad20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1ad30 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1ad40 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1ad50 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1ad60 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1ad70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1ad80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1ad90 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1ada0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1adb0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1adc0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1add0 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1ade0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1adf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1ae00 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1ae10 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1ae20 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1ae30 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1ae40 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1ae50 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1ae60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ae70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ae80 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1ae90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1aea0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1aeb0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1aec0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1aed0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1aee0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1aef0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1af00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1af10 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1af20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1af30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1af40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1af50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1af60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1af70 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1af80 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1af90 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1afa0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1afb0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1afc0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1afd0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1afe0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1aff0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1b000 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1b010 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1b020 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1b030 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1b040 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1b050 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1b060 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1b070 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1b080 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1b090 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1b0a0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1b0b0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1b0c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1b0d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1b0e0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1b0f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1b100 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1b110 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b120 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1b130 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1b140 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1b150 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1b160 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1b170 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1b180 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1b190 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1b1a0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1b1b0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1b1c0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1b1d0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1b1e0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1b1f0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1b200 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1b210 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1b220 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1b230 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1b240 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1b250 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1b260 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1b270 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1b280 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1b290 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1b2a0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1b2b0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1b2c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1b2d0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1b2e0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1b2f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1b300 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1b310 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1b320 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1b330 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1b340 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1b350 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1b360 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1b370 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1b380 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1b390 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1b3a0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1b3b0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1b3c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1b3d0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1b3e0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1b3f0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1b400 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1b410 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1b420 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1b430 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1b440 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1b450 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1b460 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1b470 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1b480 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1b490 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1b4a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b4b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1b4c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1b4d0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1b4e0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1b4f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1b500 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1b510 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1b520 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1b530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b540 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1b550 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1b560 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1b570 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1b580 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1b590 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1b5a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1b5b0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1b5c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1b5d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1b5e0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1b5f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1b600 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1b610 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1b620 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1b630 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1b640 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1b650 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1b660 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1b670 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1b680 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1b690 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1b6a0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1b6b0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1b6c0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1b6d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1b6e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1b6f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1b700 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1b710 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1b720 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1b730 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1b740 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1b750 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1b760 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1b770 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1b780 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1b790 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1b7a0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1b7b0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1b7c0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1b7d0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1b7e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1b7f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1b800 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1b810 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1b820 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1b830 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1b840 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1b850 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1b860 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1b870 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1b880 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1b890 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1b8a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1b8b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1b8c0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1b8d0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1b8e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1b8f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1b900 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1b910 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1b920 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1b930 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1b940 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1b950 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1b960 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1b970 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1b980 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1b990 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1b9a0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1b9b0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1b9c0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1b9d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1b9e0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1b9f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1ba00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1ba10 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ba20 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1ba30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1ba40 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1ba50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ba60 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1ba70 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1ba80 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1ba90 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1baa0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1bab0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1bac0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1bad0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bae0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1baf0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1bb00 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1bb10 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1bb20 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1bb30 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1bb40 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1bb50 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1bb60 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1bb70 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1bb80 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1bb90 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1bba0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1bbb0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1bbc0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1bbd0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1bbe0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1bbf0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1bc00 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1bc10 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1bc20 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1bc30 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1bc40 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1bc50 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1bc60 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1bc70 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1bc80 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1bc90 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1bca0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1bcb0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1bcc0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1bcd0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1bce0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1bcf0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1bd00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1bd10 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1bd20 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1bd30 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1bd40 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1bd50 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1bd60 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1bd70 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1bd80 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1bd90 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1bda0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1bdb0 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1bdc0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1bdd0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1bde0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1bdf0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1be00 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1be10 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1be20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1be30 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1be40 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1be50 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1be60 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1be70 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1be80 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1be90 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1bea0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1beb0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1bec0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1bed0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1bee0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1bef0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1bf00 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1bf10 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1bf20 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1bf30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1bf40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1bf50 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1bf60 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1bf70 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1bf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1bf90 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1bfa0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1bfb0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1bfc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1bfd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1bfe0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1bff0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1c000 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1c010 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1c020 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1c030 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1c040 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1c050 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1c060 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c070 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c080 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1c090 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1c0a0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1c0b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c0c0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1c0d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1c0e0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1c0f0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1c100 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1c110 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1c120 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1c130 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1c140 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1c150 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1c160 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1c170 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1c180 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1c190 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1c1a0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1c1b0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1c1c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c1d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1c1e0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1c1f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1c200 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1c210 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1c220 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1c230 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1c240 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1c250 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1c260 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1c270 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1c280 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1c290 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1c2a0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1c2b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1c2c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1c2d0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1c2e0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1c2f0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1c300 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c310 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1c320 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1c330 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c340 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1c350 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1c360 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1c370 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1c380 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1c390 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1c3a0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1c3b0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1c3c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1c3d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c3e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c3f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1c400 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1c410 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1c420 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c430 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1c440 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1c450 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1c460 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1c470 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1c480 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1c490 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1c4a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1c4b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1c4c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1c4d0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1c4e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1c4f0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c500 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1c510 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1c520 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1c530 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1c540 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1c550 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1c560 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1c570 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1c580 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1c590 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1c5a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1c5b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1c5c0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1c5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1c5e0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1c5f0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1c600 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1c610 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1c620 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1c630 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1c640 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1c650 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1c660 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1c670 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1c680 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1c690 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1c6a0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1c6b0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1c6c0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1c6d0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1c6e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1c6f0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1c700 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1c710 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c720 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1c730 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1c740 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1c750 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1c760 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1c770 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1c780 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1c790 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1c7a0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1c7b0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1c7c0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1c7d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1c7e0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1c7f0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1c800 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1c810 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1c820 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1c830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1c840 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1c850 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1c860 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1c870 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1c880 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1c890 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1c8a0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1c8b0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1c8c0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1c8d0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1c8e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1c8f0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1c900 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1c910 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1c920 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1c930 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1c940 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1c950 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1c960 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1c970 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1c980 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1c990 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1c9a0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1c9b0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1c9c0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1c9d0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1c9e0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1c9f0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1ca00 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1ca10 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1ca20 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1ca30 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1ca40 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1ca50 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1ca60 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1ca70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1ca80 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1ca90 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1caa0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1cab0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1cac0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1cad0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1cae0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1caf0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1cb00 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1cb10 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1cb20 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1cb30 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1cb40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1cb50 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1cb60 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1cb70 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1cb80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1cb90 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1cba0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1cbb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1cbc0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1cbd0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1cbe0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1cbf0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1cc00 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1cc10 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1cc20 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1cc30 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1cc40 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1cc50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cc60 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1cc70 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1cc80 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1cc90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cca0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ccb0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ccc0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1ccd0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1cce0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1ccf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cd00 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1cd10 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1cd20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1cd30 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1cd40 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1cd50 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1cd60 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1cd70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1cd80 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1cd90 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1cda0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1cdb0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1cdc0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1cdd0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1cde0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1cdf0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1ce00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1ce10 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1ce20 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1ce30 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1ce40 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1ce50 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1ce60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1ce70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1ce80 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1ce90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1cea0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1ceb0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1cec0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1ced0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1cee0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1cef0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1cf00 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1cf10 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1cf20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1cf30 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1cf40 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1cf50 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1cf60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1cf70 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1cf80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1cf90 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1cfa0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1cfb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1cfc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1cfd0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1cfe0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1cff0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1d000 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1d010 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1d020 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1d030 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1d040 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1d050 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1d060 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1d070 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1d080 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d090 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1d0a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d0b0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1d0c0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1d0d0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1d0e0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1d0f0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1d100 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1d110 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1d120 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1d130 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1d140 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1d150 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1d160 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1d170 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1d180 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1d190 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1d1a0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1d1b0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1d1c0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1d1d0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1d1e0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1d1f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1d200 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1d210 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1d220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1d230 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1d240 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1d250 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1d260 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1d270 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1d280 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1d290 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1d2a0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1d2b0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1d2c0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1d2d0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1d2e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1d2f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d300 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1d310 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1d320 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1d330 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1d340 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1d350 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1d360 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1d370 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1d380 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1d390 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1d3a0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1d3b0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1d3c0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1d3d0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1d3e0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1d3f0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1d400 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1d410 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1d420 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1d430 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1d440 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1d450 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1d460 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1d470 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1d480 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1d490 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1d4a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1d4b0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1d4c0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1d4d0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1d4e0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1d4f0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1d500 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1d510 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1d520 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1d530 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1d540 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1d550 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1d560 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1d570 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1d580 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1d590 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1d5a0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1d5b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1d5c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d5d0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1d5e0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1d5f0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1d600 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1d610 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1d620 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1d630 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1d640 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1d650 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1d660 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1d670 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1d680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d6a0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1d6b0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1d6c0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1d6d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d6e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1d6f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1d700 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1d710 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d720 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1d730 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1d740 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d750 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d770 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1d780 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1d790 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1d7a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1d7b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d7c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1d7d0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1d7e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d7f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d800 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d810 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1d820 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1d830 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1d840 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1d850 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d860 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1d870 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1d880 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1d890 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d8a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d8b0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1d8c0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1d8d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1d8e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d8f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d900 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1d910 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1d920 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1d930 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d950 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1d960 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1d970 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d980 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d9a0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1d9b0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1d9c0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1d9d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d9e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d9f0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1da00 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1da10 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1da20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1da30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1da40 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1da50 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1da60 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1da70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1da80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1da90 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1daa0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1dab0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1dac0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1dad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1dae0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1daf0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1db00 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1db10 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1db20 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1db30 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1db40 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1db50 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1db60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1db70 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1db80 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1db90 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1dba0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1dbb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1dbc0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1dbd0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1dbe0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1dbf0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1dc00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1dc10 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1dc20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1dc30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1dc40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1dc50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dc60 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1dc70 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1dc80 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1dc90 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1dca0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1dcb0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1dcc0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1dcd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1dce0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1dcf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dd00 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1dd10 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1dd20 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1dd30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dd40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dd50 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1dd60 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1dd70 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1dd80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1dd90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dda0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1ddb0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1ddc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ddd0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1dde0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ddf0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1de00 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1de10 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1de20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1de30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1de40 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1de50 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1de60 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1de70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1de80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1de90 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1dea0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1deb0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1dec0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ded0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1dee0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1def0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1df00 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1df10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1df20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1df30 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1df40 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1df50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1df60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1df70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1df80 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1df90 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1dfa0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1dfb0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1dfc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1dfd0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1dfe0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1dff0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1e000 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1e010 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1e020 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1e030 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1e040 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1e050 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1e060 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1e070 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1e080 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1e090 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1e0a0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1e0b0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1e0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1e0d0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1e0e0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1e0f0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1e100 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1e110 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1e120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1e130 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1e140 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1e150 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1e160 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1e170 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1e180 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1e190 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1e1a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1e1b0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1e1c0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1e1d0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1e1e0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1e1f0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1e200 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1e210 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1e220 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1e230 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1e240 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1e250 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1e260 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1e270 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1e280 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1e290 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1e2a0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1e2b0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1e2c0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1e2d0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1e2e0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1e2f0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1e300 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1e310 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1e320 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1e330 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1e340 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1e350 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1e360 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1e370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1e380 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1e390 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1e3a0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1e3b0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1e3c0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1e3d0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1e3e0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1e3f0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1e400 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1e410 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1e420 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1e430 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1e440 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1e450 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1e460 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1e470 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1e480 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1e490 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1e4a0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1e4b0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1e4c0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1e4d0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1e4e0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1e4f0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1e500 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1e510 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1e520 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1e530 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1e540 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e550 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1e560 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1e570 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1e580 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1e590 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1e5a0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1e5b0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1e5c0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1e5d0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1e5e0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1e5f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1e600 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1e610 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1e620 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1e630 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1e640 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1e650 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1e660 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1e670 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1e680 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1e690 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1e6a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1e6b0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1e6c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1e6d0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1e6e0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1e6f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e700 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1e710 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1e720 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1e730 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1e740 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1e750 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1e760 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1e770 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1e780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1e790 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1e7a0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1e7b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1e7c0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1e7d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1e7e0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1e7f0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1e800 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1e810 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1e820 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1e830 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1e840 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1e850 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1e860 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1e870 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1e880 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1e890 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1e8a0 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1e8b0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1e8c0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1e8d0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1e8e0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1e8f0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1e900 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1e910 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1e920 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1e930 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1e940 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1e950 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1e960 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1e970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1e980 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1e990 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1e9a0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1e9b0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1e9c0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1e9d0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1e9e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e9f0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1ea00 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1ea10 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1ea20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1ea30 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1ea40 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1ea50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1ea60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1ea70 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1ea80 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1ea90 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1eaa0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1eab0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1eac0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1ead0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1eae0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1eaf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1eb00 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1eb10 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1eb20 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1eb30 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1eb40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1eb50 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1eb60 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1eb70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1eb80 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1eb90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1eba0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1ebb0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1ebc0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1ebd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1ebe0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1ebf0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1ec00 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1ec10 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1ec20 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1ec30 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1ec40 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1ec50 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ec60 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1ec70 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1ec80 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1ec90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1eca0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1ecb0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1ecc0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1ecd0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1ece0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1ecf0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1ed00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1ed10 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1ed20 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ed30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ed40 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ed50 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ed60 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1ed70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ed80 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1ed90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1eda0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1edb0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1edc0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1edd0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1ede0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1edf0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1ee00 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1ee10 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1ee20 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ee30 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1ee40 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1ee50 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1ee60 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1ee70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1ee80 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1ee90 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1eea0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1eeb0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1eec0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1eed0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1eee0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1eef0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1ef00 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1ef10 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1ef20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1ef30 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1ef40 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1ef50 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1ef60 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1ef70 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1ef80 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1ef90 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1efa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1efb0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1efc0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1efd0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1efe0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1eff0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1f000 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1f010 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1f020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1f030 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1f040 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1f050 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1f060 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1f070 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1f080 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1f090 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1f0a0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1f0b0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1f0c0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1f0d0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1f0e0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1f0f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f100 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1f110 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1f120 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1f130 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1f140 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1f150 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1f160 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1f170 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1f180 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1f190 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1f1a0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1f1b0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1f1c0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1f1d0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1f1e0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1f1f0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1f200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1f210 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1f220 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1f230 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1f240 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1f250 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1f260 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1f270 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1f280 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1f290 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1f2a0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1f2b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1f2c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f2d0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1f2e0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f2f0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1f300 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1f310 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1f320 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1f330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f340 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1f350 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1f360 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1f370 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1f380 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1f390 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1f3a0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1f3b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1f3c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1f3d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1f3e0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1f3f0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1f400 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f410 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1f420 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1f430 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1f440 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1f450 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1f460 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1f470 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1f480 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1f490 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1f4a0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1f4b0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1f4c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1f4d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1f4e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1f4f0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1f500 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1f510 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1f520 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f530 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1f540 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1f550 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1f560 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1f570 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1f580 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1f590 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1f5a0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1f5b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1f5c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1f5d0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1f5e0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1f5f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1f600 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f610 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1f620 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1f630 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1f640 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1f650 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1f660 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f670 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1f680 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1f690 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1f6a0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1f6b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f6c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1f6d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1f6e0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1f6f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1f700 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1f710 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1f720 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1f730 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1f740 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1f750 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1f760 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1f770 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1f780 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1f790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1f7a0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1f7b0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1f7c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f7d0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1f7e0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1f7f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1f800 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1f810 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1f820 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1f830 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1f840 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1f850 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1f860 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1f870 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1f880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f890 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1f8a0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1f8b0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1f8c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1f8d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1f8e0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1f8f0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1f900 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1f910 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1f920 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1f930 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1f940 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1f950 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f960 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1f970 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1f980 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1f990 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1f9a0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f9b0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1f9c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1f9d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1f9e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1f9f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1fa00 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1fa10 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1fa20 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1fa30 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1fa40 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1fa50 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1fa60 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1fa70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1fa80 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1fa90 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1faa0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1fab0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1fac0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1fad0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1fae0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1faf0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1fb00 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1fb10 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1fb20 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1fb30 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1fb40 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1fb50 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1fb60 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fb70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1fb80 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1fb90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fba0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1fbb0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1fbc0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1fbd0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1fbe0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1fbf0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1fc00 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1fc10 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1fc20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1fc30 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1fc40 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1fc50 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1fc60 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1fc70 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1fc80 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1fc90 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1fca0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1fcb0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1fcc0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1fcd0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1fce0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1fcf0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1fd00 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1fd10 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1fd20 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1fd30 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1fd40 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1fd50 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1fd60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1fd70 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1fd80 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1fd90 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1fda0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1fdb0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1fdc0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1fdd0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1fde0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1fdf0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1fe00 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1fe10 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1fe20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1fe30 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
1fe40 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
1fe50 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
1fe60 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1fe70 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
1fe80 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1fe90 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
1fea0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
1feb0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1fec0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
1fed0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
1fee0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
1fef0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
1ff00 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
1ff10 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
1ff20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
1ff30 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
1ff40 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
1ff50 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
1ff60 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
1ff70 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1ff80 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
1ff90 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1ffa0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
1ffb0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
1ffc0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
1ffd0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1ffe0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
1fff0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
20000 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
20010 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
20020 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
20030 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20040 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20050 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
20060 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
20070 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
20080 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
20090 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
200a0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
200b0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
200c0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
200d0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
200e0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
200f0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
20100 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
20110 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
20120 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
20130 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
20140 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
20150 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
20160 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20170 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
20180 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
20190 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
201a0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
201b0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
201c0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
201d0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
201e0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
201f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
20200 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
20210 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
20220 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
20230 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
20240 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
20250 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
20260 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
20270 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
20280 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
20290 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
202a0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
202b0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
202c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
202d0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
202e0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
202f0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
20300 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
20310 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
20320 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
20330 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
20340 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
20350 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
20360 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
20370 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
20380 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
20390 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
203a0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
203b0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
203c0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
203d0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
203e0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
203f0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
20400 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
20410 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
20420 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
20430 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
20440 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
20450 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
20460 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
20470 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
20480 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
20490 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
204a0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
204b0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
204c0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
204d0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
204e0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
204f0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
20500 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
20510 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
20520 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
20530 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
20540 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
20550 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
20560 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
20570 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
20580 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
20590 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
205a0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
205b0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
205c0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
205d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
205e0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
205f0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
20600 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
20610 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
20620 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
20630 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
20640 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20650 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20660 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
20670 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
20680 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
20690 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
206a0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
206b0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
206c0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
206d0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
206e0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
206f0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
20700 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
20710 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
20720 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
20730 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20740 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20750 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
20760 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
20770 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
20780 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20790 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
207a0 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
207b0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
207c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
207d0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
207e0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
207f0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
20800 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
20810 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
20820 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
20830 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
20840 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
20850 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
20860 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
20870 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
20880 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
20890 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
208a0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
208b0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
208c0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
208d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
208e0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
208f0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
20900 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
20910 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
20920 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
20930 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
20940 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
20950 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
20960 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
20970 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
20980 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
20990 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
209a0 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
209b0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
209c0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
209d0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
209e0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
209f0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
20a00 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
20a10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
20a20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20a30 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
20a40 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
20a50 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
20a60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20a70 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
20a80 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
20a90 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
20aa0 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
20ab0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
20ac0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
20ad0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
20ae0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20af0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
20b00 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
20b10 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
20b20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
20b30 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
20b40 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
20b50 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
20b60 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
20b70 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
20b80 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20b90 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
20ba0 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
20bb0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
20bc0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
20bd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
20be0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
20bf0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
20c00 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
20c10 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
20c20 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
20c30 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
20c40 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20c50 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
20c60 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20c70 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
20c80 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
20c90 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
20ca0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
20cb0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
20cc0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
20cd0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
20ce0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20cf0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
20d00 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
20d10 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
20d20 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
20d30 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
20d40 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
20d50 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
20d60 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
20d70 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
20d80 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
20d90 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
20da0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
20db0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
20dc0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
20dd0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
20de0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
20df0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
20e00 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
20e10 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
20e20 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
20e30 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
20e40 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
20e50 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
20e60 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
20e70 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
20e80 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
20e90 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
20ea0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
20eb0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
20ec0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
20ed0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
20ee0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
20ef0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
20f00 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20f10 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
20f20 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
20f30 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
20f40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
20f50 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
20f60 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
20f70 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
20f80 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
20f90 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
20fa0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
20fb0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
20fc0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
20fd0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
20fe0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
20ff0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
21000 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
21010 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
21020 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
21030 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
21040 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21050 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
21060 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
21070 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
21080 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
21090 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
210a0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
210b0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
210c0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
210d0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
210e0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
210f0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
21100 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
21110 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
21120 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
21130 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
21140 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
21150 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21160 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21170 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21180 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
21190 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
211a0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
211b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
211c0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
211d0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
211e0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
211f0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
21200 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
21210 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21220 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21230 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
21240 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
21250 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
21260 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21270 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
21280 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
21290 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
212a0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
212b0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
212c0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
212d0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
212e0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
212f0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
21300 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
21310 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
21320 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
21330 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21340 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
21350 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
21360 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
21370 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
21380 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
21390 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
213a0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
213b0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
213c0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
213d0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
213e0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
213f0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
21400 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
21410 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
21420 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
21430 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
21440 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
21450 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
21460 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
21470 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
21480 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
21490 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
214a0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
214b0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
214c0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
214d0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
214e0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
214f0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
21500 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
21510 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
21520 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
21530 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21540 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
21550 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
21560 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
21570 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
21580 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21590 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
215a0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
215b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
215c0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
215d0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
215e0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
215f0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
21600 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
21610 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
21620 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
21630 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
21640 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
21650 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
21660 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21670 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21680 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21690 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
216a0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
216b0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
216c0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
216d0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
216e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
216f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
21700 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
21710 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
21720 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
21730 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
21740 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
21750 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
21760 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
21770 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21780 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
21790 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
217a0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
217b0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
217c0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
217d0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
217e0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
217f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21800 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21810 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
21820 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
21830 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
21840 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21850 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21860 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
21870 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
21880 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
21890 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
218a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
218b0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
218c0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
218d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
218e0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
218f0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
21900 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21910 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21920 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
21930 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
21940 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
21950 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
21960 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
21970 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
21980 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
21990 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
219a0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
219b0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
219c0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
219d0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
219e0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
219f0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
21a00 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
21a10 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
21a20 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
21a30 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
21a40 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
21a50 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
21a60 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
21a70 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
21a80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
21a90 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
21aa0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
21ab0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
21ac0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
21ad0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
21ae0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
21af0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
21b00 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21b10 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
21b20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
21b30 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
21b40 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
21b50 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
21b60 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
21b70 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
21b80 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
21b90 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
21ba0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
21bb0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
21bc0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
21bd0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
21be0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
21bf0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
21c00 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
21c10 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
21c20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
21c30 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
21c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21c50 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
21c60 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
21c70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
21c80 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
21c90 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
21ca0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
21cb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
21cc0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
21cd0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21ce0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
21cf0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
21d00 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
21d10 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
21d20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
21d30 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
21d40 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
21d50 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
21d60 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21d70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21d80 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
21d90 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
21da0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
21db0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
21dc0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
21dd0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
21de0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
21df0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
21e00 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
21e10 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
21e20 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
21e30 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
21e40 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
21e50 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
21e60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
21e70 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
21e80 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
21e90 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
21ea0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
21eb0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
21ec0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
21ed0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
21ee0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
21ef0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
21f00 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
21f10 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
21f20 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
21f30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
21f40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
21f50 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
21f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
21f70 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
21f80 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
21f90 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
21fa0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
21fb0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
21fc0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
21fd0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
21fe0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
21ff0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
22000 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
22010 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
22020 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
22030 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
22040 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
22050 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
22060 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
22070 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
22080 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
22090 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
220a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
220b0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
220c0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
220d0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
220e0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
220f0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
22100 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
22110 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
22120 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
22130 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
22140 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
22150 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
22160 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
22170 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
22180 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
22190 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
221a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
221b0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
221c0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
221d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
221e0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
221f0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
22200 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
22210 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
22220 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
22230 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
22240 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
22250 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
22260 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
22270 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
22280 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
22290 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
222a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
222b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
222c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
222d0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
222e0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
222f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22300 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
22310 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
22320 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
22330 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
22340 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
22350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22360 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
22370 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
22380 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
22390 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
223a0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
223b0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
223c0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
223d0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
223e0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
223f0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
22400 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
22410 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
22420 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
22430 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
22440 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22450 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
22460 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
22470 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
22480 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
22490 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
224a0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
224b0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
224c0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
224d0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
224e0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
224f0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
22500 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
22510 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
22520 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
22530 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
22540 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
22550 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
22560 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
22570 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
22580 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
22590 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
225a0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
225b0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
225c0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
225d0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
225e0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
225f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
22600 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
22610 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
22620 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
22630 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
22640 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22650 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
22660 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
22670 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
22680 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
22690 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
226a0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
226b0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
226c0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
226d0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
226e0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
226f0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
22700 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
22710 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
22720 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
22730 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
22740 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
22750 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
22760 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
22770 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
22780 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
22790 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
227a0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
227b0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
227c0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
227d0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
227e0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
227f0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
22800 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
22810 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
22820 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
22830 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
22840 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
22850 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
22860 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
22870 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
22880 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
22890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
228a0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
228b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
228c0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
228d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
228e0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
228f0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
22900 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
22910 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
22920 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
22930 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
22940 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
22950 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
22960 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
22970 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
22980 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
22990 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
229a0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
229b0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
229c0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
229d0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
229e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
229f0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
22a00 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
22a10 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
22a20 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
22a30 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
22a40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
22a50 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
22a60 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
22a70 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
22a80 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
22a90 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
22aa0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
22ab0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22ac0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
22ad0 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
22ae0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
22af0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
22b00 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
22b10 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
22b20 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
22b30 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
22b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b50 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
22b60 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
22b70 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
22b80 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
22b90 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
22ba0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
22bb0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
22bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22bd0 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
22be0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
22bf0 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
22c00 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
22c10 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
22c20 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
22c30 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
22c40 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
22c50 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
22c60 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
22c70 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
22c80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
22c90 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
22ca0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
22cb0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
22cc0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
22cd0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
22ce0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
22cf0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
22d00 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
22d10 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
22d20 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
22d30 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
22d40 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
22d50 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
22d60 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
22d70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
22d80 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
22d90 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
22da0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
22db0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
22dc0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
22dd0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
22de0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22df0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
22e00 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
22e10 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
22e20 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
22e30 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
22e40 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
22e50 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
22e60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
22e70 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
22e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22e90 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
22ea0 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
22eb0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
22ec0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
22ed0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
22ee0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
22ef0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
22f00 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
22f10 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
22f20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
22f30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
22f40 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
22f50 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
22f60 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
22f70 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
22f80 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
22f90 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
22fa0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
22fb0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
22fc0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
22fd0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
22fe0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
22ff0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
23000 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
23010 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
23020 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
23030 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
23040 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
23050 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
23060 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
23070 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
23080 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
23090 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
230a0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
230b0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
230c0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
230d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
230e0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
230f0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
23100 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
23110 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
23120 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
23130 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
23140 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
23150 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
23160 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
23170 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
23180 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
23190 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
231a0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
231b0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
231c0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
231d0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
231e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
231f0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
23200 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
23210 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
23220 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
23230 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
23240 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
23250 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
23260 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
23270 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
23280 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
23290 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
232a0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
232b0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
232c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
232d0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
232e0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
232f0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
23300 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
23310 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
23320 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
23330 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
23340 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
23350 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
23360 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
23370 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
23380 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
23390 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
233a0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
233b0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
233c0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
233d0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
233e0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
233f0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
23400 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
23410 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
23420 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
23430 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
23440 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
23450 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
23460 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
23470 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
23480 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
23490 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
234a0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
234b0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
234c0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
234d0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
234e0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
234f0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
23500 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
23510 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
23520 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
23530 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
23540 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
23550 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23560 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
23570 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
23580 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
23590 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
235a0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
235b0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
235c0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
235d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
235e0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
235f0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
23600 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
23610 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
23620 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
23630 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
23640 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
23650 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
23660 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
23670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23680 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
23690 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
236a0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
236b0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
236c0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
236d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
236e0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
236f0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
23700 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
23710 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
23720 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
23730 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
23740 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
23750 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
23760 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
23770 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
23780 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
23790 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
237a0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
237b0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
237c0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
237d0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
237e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
237f0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
23800 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
23810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23820 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
23830 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
23840 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
23850 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
23860 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23870 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
23880 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23890 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
238a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
238b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
238c0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
238d0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
238e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
238f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
23900 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23910 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
23920 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23930 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
23940 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
23950 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
23960 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
23970 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
23980 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
23990 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
239a0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
239b0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
239c0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
239d0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
239e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
239f0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
23a00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23a10 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
23a20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23a30 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
23a40 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
23a50 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
23a60 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23a70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
23a80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
23a90 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23aa0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23ab0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
23ac0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23ad0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
23ae0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
23af0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
23b00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23b10 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
23b20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23b30 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
23b40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23b50 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
23b60 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
23b70 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23b80 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
23b90 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
23ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
23bb0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
23bc0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
23bd0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
23be0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
23bf0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
23c00 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
23c10 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
23c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23c30 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
23c40 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
23c50 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
23c60 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
23c70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23c80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
23c90 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
23ca0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23cb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
23cc0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
23cd0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
23ce0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
23cf0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23d00 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
23d10 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
23d20 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
23d30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
23d40 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23d50 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
23d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
23d70 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
23d80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23d90 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23da0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
23db0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
23dc0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
23dd0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
23de0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23df0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
23e00 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
23e10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23e20 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
23e30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23e40 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
23e50 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
23e60 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
23e70 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
23e80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23e90 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
23ea0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
23eb0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
23ec0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
23ed0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
23ee0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
23ef0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
23f00 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
23f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23f20 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
23f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f40 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
23f50 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
23f60 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23f70 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
23f80 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
23f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23fa0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
23fb0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23fc0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
23fd0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
23fe0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
23ff0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
24000 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
24010 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
24020 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
24030 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
24040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24050 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
24060 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
24070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24080 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
24090 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
240a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
240b0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
240c0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
240d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
240e0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
240f0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
24100 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24110 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
24120 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
24130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
24140 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
24150 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
24160 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
24170 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
24180 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
24190 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
241a0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
241b0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
241c0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
241d0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
241e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
241f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
24200 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
24210 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
24220 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
24230 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
24240 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
24250 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24260 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
24270 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
24280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24290 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
242a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
242b0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
242c0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
242d0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
242e0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
242f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
24300 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
24310 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
24320 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
24330 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
24340 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
24350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24360 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
24370 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
24380 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24390 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
243a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
243b0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
243c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
243d0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
243e0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
243f0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
24400 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
24410 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
24420 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
24430 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24440 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
24450 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
24460 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
24470 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
24480 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
24490 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
244a0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
244b0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
244c0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
244d0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
244e0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
244f0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
24500 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
24510 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
24520 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
24530 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
24540 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
24550 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
24560 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
24570 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
24580 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
24590 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
245a0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
245b0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
245c0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
245d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
245e0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
245f0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
24600 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
24610 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
24620 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
24630 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
24640 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
24650 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
24660 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
24670 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
24680 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
24690 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
246a0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
246b0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
246c0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
246d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
246e0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
246f0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
24700 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
24710 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
24720 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
24730 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
24740 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
24750 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
24760 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
24770 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
24780 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
24790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
247a0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
247b0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
247c0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
247d0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
247e0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
247f0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
24800 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
24810 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
24820 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
24830 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
24840 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
24850 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
24860 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
24870 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
24880 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
24890 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
248a0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
248b0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
248c0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
248d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
248e0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
248f0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
24900 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
24910 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
24920 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
24930 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
24940 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
24950 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
24960 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
24970 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
24980 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
24990 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
249a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
249b0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
249c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
249d0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
249e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
249f0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
24a00 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
24a10 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
24a20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
24a30 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
24a40 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
24a50 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
24a60 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
24a70 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24a80 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
24a90 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
24aa0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
24ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
24ac0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
24ad0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
24ae0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
24af0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
24b00 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
24b10 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
24b20 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
24b30 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
24b40 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
24b50 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
24b60 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
24b70 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
24b80 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
24b90 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
24ba0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
24bb0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
24bc0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
24bd0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
24be0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
24bf0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
24c00 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
24c10 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
24c20 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
24c30 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
24c40 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
24c50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
24c60 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
24c70 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
24c80 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
24c90 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
24ca0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
24cb0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
24cc0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
24cd0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
24ce0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
24cf0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
24d00 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
24d10 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
24d20 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
24d30 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
24d40 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
24d50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
24d60 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
24d70 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
24d80 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
24d90 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
24da0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
24db0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
24dc0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
24dd0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
24de0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
24df0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
24e00 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
24e10 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
24e20 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
24e30 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
24e40 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
24e50 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
24e60 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
24e70 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
24e80 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
24e90 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
24ea0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
24eb0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
24ec0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
24ed0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
24ee0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
24ef0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
24f00 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
24f10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24f20 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
24f30 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
24f40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
24f50 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
24f60 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
24f70 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
24f80 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
24f90 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
24fa0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
24fb0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
24fc0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
24fd0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
24fe0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
24ff0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
25000 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
25010 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
25020 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
25030 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
25040 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
25050 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
25060 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
25070 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
25080 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
25090 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
250a0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
250b0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
250c0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
250d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
250e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
250f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
25100 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
25110 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
25120 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
25130 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
25140 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
25150 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
25160 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25170 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25180 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25190 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
251a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
251b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
251c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
251d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
251e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
251f0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
25200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25210 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25220 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
25230 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25240 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25250 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25260 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25270 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
25280 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25290 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
252a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
252b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
252c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
252d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
252e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
252f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
25300 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
25310 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
25320 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
25330 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
25340 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25350 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
25360 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25370 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25380 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25390 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
253a0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
253b0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
253c0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
253d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
253e0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
253f0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25400 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25410 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25420 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25430 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25440 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
25450 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25460 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25470 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25480 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
25490 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
254a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
254b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
254c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
254d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
254e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
254f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25500 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25510 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25520 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25530 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25540 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25550 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25560 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25570 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25580 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25590 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
255a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
255b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
255c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
255d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
255e0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
255f0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
25600 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
25610 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
25620 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
25630 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
25640 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
25650 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
25660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25670 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
25680 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
25690 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
256a0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
256b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
256c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
256d0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
256e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
256f0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
25700 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25710 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
25720 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
25730 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
25740 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
25750 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25760 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
25770 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25780 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
25790 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
257a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
257b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
257c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
257d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
257e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
257f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
25800 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
25810 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25820 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25830 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
25840 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
25850 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25860 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
25870 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
25880 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
25890 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
258a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
258b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
258c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
258d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
258e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
258f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
25900 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
25910 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
25920 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
25930 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
25940 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
25950 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
25960 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
25970 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
25980 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
25990 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
259a0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
259b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
259c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
259d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
259e0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
259f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
25a00 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
25a10 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
25a20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
25a30 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
25a40 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
25a50 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
25a60 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
25a70 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
25a80 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
25a90 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
25aa0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
25ab0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
25ac0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
25ad0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
25ae0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
25af0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
25b00 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
25b10 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
25b20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
25b30 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
25b40 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
25b50 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
25b60 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
25b70 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
25b80 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
25b90 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
25ba0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
25bb0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
25bc0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
25bd0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
25be0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
25bf0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
25c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
25c10 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
25c20 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
25c30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
25c40 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
25c50 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
25c60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25c70 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
25c80 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25c90 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
25ca0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
25cb0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
25cc0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
25cd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25ce0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
25cf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25d00 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
25d10 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
25d20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25d30 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
25d40 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
25d50 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
25d60 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
25d70 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
25d80 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
25d90 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
25da0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
25db0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
25dc0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
25dd0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
25de0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25df0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
25e00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
25e10 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
25e20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
25e30 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
25e40 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
25e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25e60 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
25e70 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25e80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
25e90 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
25ea0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
25eb0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
25ec0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
25ed0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
25ee0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
25ef0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
25f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25f10 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
25f20 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
25f30 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
25f40 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
25f50 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
25f60 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
25f70 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
25f80 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
25f90 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
25fa0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
25fb0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
25fc0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
25fd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
25fe0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
25ff0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
26000 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
26020 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
26030 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
26040 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
26050 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26060 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
26070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
26080 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
26090 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
260a0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
260b0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
260c0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
260d0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
260e0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
260f0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
26100 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
26110 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
26120 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
26130 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
26140 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
26150 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
26160 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
26170 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
26180 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
26190 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
261a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
261b0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
261c0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
261d0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
261e0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
261f0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
26200 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26210 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
26220 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
26230 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
26240 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
26250 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26260 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
26270 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
26280 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
26290 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
262a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
262b0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
262c0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
262d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
262e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
262f0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
26300 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
26310 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
26320 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
26330 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
26340 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
26350 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
26360 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26370 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
26380 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
26390 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
263a0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
263b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
263c0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
263d0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
263e0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
263f0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
26400 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
26410 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
26420 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
26430 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
26440 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
26450 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
26460 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
26470 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
26480 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
26490 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
264a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
264b0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
264c0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
264d0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
264e0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
264f0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26500 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
26510 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
26520 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
26530 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
26540 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
26550 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
26560 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
26570 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
26580 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
26590 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
265a0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
265b0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
265c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
265d0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
265e0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
265f0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
26600 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
26610 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
26620 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
26630 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
26640 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
26650 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
26660 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26670 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
26680 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
26690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
266a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
266b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
266c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
266d0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
266e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
266f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26700 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
26710 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
26720 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26730 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26740 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
26750 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
26760 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
26770 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
26780 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
26790 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
267a0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
267b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
267c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
267d0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
267e0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
267f0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
26800 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
26810 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
26820 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
26830 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
26840 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
26850 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
26860 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
26870 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
26880 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
26890 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
268a0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
268b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
268c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
268d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
268e0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
268f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
26900 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26910 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
26920 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
26930 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
26940 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26950 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
26960 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
26970 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
26980 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
26990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
269a0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
269b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
269c0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
269d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
269e0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
269f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
26a00 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
26a10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
26a20 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
26a30 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
26a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
26a50 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
26a60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26a70 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
26a80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
26a90 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
26aa0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
26ab0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
26ac0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
26ad0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
26ae0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
26af0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
26b00 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
26b10 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
26b20 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
26b30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
26b40 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
26b50 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
26b60 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
26b70 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
26b80 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
26b90 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
26ba0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
26bb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
26bc0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
26bd0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
26be0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
26bf0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
26c00 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
26c10 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
26c20 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
26c30 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
26c40 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
26c50 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
26c60 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
26c70 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
26c80 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
26c90 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
26ca0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
26cb0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
26cc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
26cd0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
26ce0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
26cf0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
26d00 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
26d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26d20 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
26d30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26d40 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
26d50 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
26d60 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
26d70 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
26d80 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
26d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26da0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
26db0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
26dc0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
26dd0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
26de0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
26df0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
26e00 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
26e10 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
26e20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
26e30 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
26e40 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
26e50 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
26e60 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
26e70 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
26e80 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
26e90 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
26ea0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
26eb0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
26ec0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
26ed0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
26ee0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
26ef0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
26f00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
26f10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26f20 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
26f30 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
26f40 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
26f50 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
26f60 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
26f70 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
26f80 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
26f90 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
26fa0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
26fb0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
26fc0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
26fd0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
26fe0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
26ff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
27000 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
27010 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
27020 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
27030 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
27040 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
27050 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
27060 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
27070 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
27080 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27090 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
270a0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
270b0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
270c0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
270d0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
270e0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
270f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
27100 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
27110 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27120 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27130 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
27140 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27150 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
27160 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
27170 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
27180 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
27190 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
271a0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
271b0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
271c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
271d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
271e0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
271f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
27200 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
27210 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
27220 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
27230 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27240 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
27250 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27260 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
27270 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27280 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d   then that param
27290 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
272a0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
272b0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
272c0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
272d0 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
272e0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
272f0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
27300 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
27310 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
27320 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
27330 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
27340 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
27350 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
27360 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
27370 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
27380 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
27390 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
273a0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
273b0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
273c0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
273d0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
273e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
273f0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
27400 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
27410 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
27420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27430 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
27440 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27450 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
27460 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
27470 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
27480 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
27490 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
274a0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
274b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
274c0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
274d0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
274e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
274f0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
27500 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27510 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
27520 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
27530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27540 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
27550 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
27560 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
27570 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
27580 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
27590 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
275a0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
275b0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
275c0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
275d0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
275e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
275f0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
27600 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
27610 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
27620 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
27630 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
27640 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
27650 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
27660 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
27670 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
27680 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
27690 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
276a0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
276b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
276c0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
276d0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
276e0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
276f0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
27700 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
27710 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
27720 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
27730 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
27740 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
27750 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
27760 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
27770 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
27780 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
27790 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
277a0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
277b0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
277c0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
277d0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
277e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
277f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
27800 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
27810 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
27820 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
27830 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
27840 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
27850 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
27860 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
27870 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27880 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
27890 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
278a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
278b0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
278c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
278d0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
278e0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
278f0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
27900 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
27910 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
27920 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
27930 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
27940 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
27950 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
27960 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
27970 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
27980 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
27990 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
279a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
279b0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
279c0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
279d0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
279e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
279f0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
27a00 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
27a10 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
27a20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27a30 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
27a40 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
27a50 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
27a60 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
27a70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
27a80 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
27a90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
27aa0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
27ab0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
27ac0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
27ad0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
27ae0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
27af0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
27b00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
27b10 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
27b20 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
27b30 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
27b40 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
27b50 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
27b60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
27b70 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
27b80 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
27b90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27ba0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
27bb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27bc0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27bd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
27be0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
27bf0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
27c00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
27c10 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27c20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27c30 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
27c40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
27c50 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
27c60 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
27c70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27c80 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
27c90 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
27ca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27cb0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
27cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27cd0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
27ce0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
27cf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27d00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
27d10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
27d20 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
27d30 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
27d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27d50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27d60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
27d70 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
27d80 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
27d90 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
27da0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27db0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
27dc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27dd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
27de0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
27df0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
27e00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27e10 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
27e20 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27e30 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
27e40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
27e50 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
27e60 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
27e70 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
27e80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27e90 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
27ea0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
27eb0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
27ec0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
27ed0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
27ee0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
27ef0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
27f00 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
27f10 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
27f20 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
27f30 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
27f40 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
27f50 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
27f60 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
27f70 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
27f80 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
27f90 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
27fa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
27fb0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
27fc0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
27fd0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
27fe0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
27ff0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
28000 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
28010 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
28020 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
28030 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
28040 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
28050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
28060 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28070 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
28080 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
28090 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
280a0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
280b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
280c0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
280d0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
280e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
280f0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
28100 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
28110 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
28120 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
28130 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
28140 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28150 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
28160 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28170 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
28180 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
28190 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
281a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
281b0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
281c0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
281d0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
281e0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
281f0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
28200 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
28210 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
28220 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
28230 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
28240 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
28250 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
28260 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
28270 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
28280 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
28290 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
282a0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
282b0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
282c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
282d0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
282e0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
282f0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
28300 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
28310 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
28320 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
28330 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
28340 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
28350 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
28360 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
28370 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
28380 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
28390 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
283a0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
283b0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
283c0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
283d0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
283e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
283f0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
28400 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
28410 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
28420 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
28430 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
28440 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
28450 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
28460 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
28470 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28480 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
28490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
284a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
284b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
284c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
284d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
284e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
284f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28500 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28510 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28530 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
28540 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
28550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
28560 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
28570 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
28580 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
28590 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
285a0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
285b0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
285c0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
285d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
285e0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
285f0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
28600 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
28610 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
28620 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
28630 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
28640 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
28650 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
28660 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
28670 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
28680 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
28690 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
286a0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
286b0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
286c0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
286d0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
286e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
286f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
28700 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28710 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28720 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
28730 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28740 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28750 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
28760 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28770 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28780 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28790 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
287a0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
287b0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
287c0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
287d0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
287e0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
287f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
28800 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
28810 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
28820 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
28830 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28840 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
28850 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
28860 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
28870 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
28880 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28890 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
288a0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
288b0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
288c0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
288d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
288e0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
288f0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28900 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
28910 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
28920 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28930 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
28940 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28950 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
28960 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
28970 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28980 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
28990 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
289a0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
289b0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
289c0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
289d0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
289e0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
289f0 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
28a00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28a10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
28a20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
28a30 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
28a40 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28a60 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
28a70 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
28a80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
28a90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
28aa0 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
28ab0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
28ac0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
28ad0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
28ae0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28af0 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
28b00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
28b10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28b20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28b30 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28b40 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
28b50 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
28b60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
28b70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28b80 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
28b90 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
28ba0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
28bb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28bc0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
28bd0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
28be0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
28bf0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
28c00 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
28c10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
28c20 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
28c30 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
28c40 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
28c50 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
28c60 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28c70 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
28c80 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
28c90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28ca0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
28cb0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
28cc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28cd0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
28ce0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
28cf0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
28d00 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
28d10 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
28d20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
28d30 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
28d40 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
28d50 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
28d60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
28d70 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
28d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
28d90 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
28da0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
28db0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
28dc0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
28dd0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
28de0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
28df0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
28e00 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
28e10 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
28e20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
28e30 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
28e40 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
28e50 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
28e60 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
28e70 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
28e80 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
28e90 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
28ea0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
28eb0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
28ec0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
28ed0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
28ee0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
28ef0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
28f00 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
28f10 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
28f20 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
28f30 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
28f40 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28f50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28f60 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
28f70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
28f80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28f90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
28fa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28fb0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
28fc0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
28fd0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
28fe0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
28ff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
29000 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
29010 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
29020 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
29030 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
29040 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
29050 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
29060 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
29070 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
29080 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
29090 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
290a0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
290b0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
290c0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
290d0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
290e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
290f0 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
29100 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
29110 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
29120 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
29130 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
29140 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
29150 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
29160 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
29170 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
29180 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
29190 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
291a0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
291b0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
291c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
291d0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
291e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
291f0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
29200 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
29220 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
29230 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
29240 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
29250 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
29260 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
29270 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
29280 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
29290 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
292a0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
292b0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
292c0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
292d0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
292e0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
292f0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
29300 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
29310 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
29320 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
29330 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
29340 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
29350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29360 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
29370 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
29380 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
29390 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
293a0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
293b0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
293c0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
293d0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
293e0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
293f0 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
29400 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
29410 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
29420 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
29430 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
29440 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
29450 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
29460 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
29470 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
29480 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
29490 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
294a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
294b0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
294c0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
294d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
294e0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
294f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
29500 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
29510 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
29520 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
29530 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
29540 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
29550 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
29560 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
29570 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
29580 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
29590 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
295a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
295b0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
295c0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
295d0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
295e0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
295f0 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
29600 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
29610 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
29620 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
29630 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
29640 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
29650 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
29660 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
29670 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
29680 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
29690 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
296a0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
296b0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
296c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
296d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
296e0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
296f0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
29700 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
29710 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
29720 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
29730 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
29740 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
29750 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
29760 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
29770 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
29780 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
29790 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
297a0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
297b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
297c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
297d0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
297e0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
297f0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
29800 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
29810 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
29820 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29830 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29840 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
29850 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29860 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29870 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29880 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
29890 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
298a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
298b0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
298c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
298d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
298e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
298f0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
29900 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29910 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29930 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
29940 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29950 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29960 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
29970 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
29980 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
29990 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
299a0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
299b0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
299c0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
299d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
299e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
299f0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
29a00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
29a10 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29a20 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
29a30 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
29a40 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
29a50 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
29a60 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
29a70 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
29a80 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
29a90 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
29aa0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
29ab0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
29ac0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
29ad0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
29ae0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
29af0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
29b00 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
29b10 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
29b20 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
29b30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29b40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29b50 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
29b60 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
29b70 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
29b80 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
29b90 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
29ba0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
29bb0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
29bc0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
29bd0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
29be0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
29bf0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
29c00 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
29c10 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
29c20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
29c30 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
29c40 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
29c50 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
29c60 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
29c70 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
29c80 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
29c90 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
29ca0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
29cb0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
29cc0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
29cd0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
29ce0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
29cf0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
29d00 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
29d10 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
29d20 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
29d30 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
29d40 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
29d50 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
29d60 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
29d70 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
29d80 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
29d90 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
29da0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
29db0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
29dc0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
29dd0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
29de0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
29df0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
29e00 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
29e10 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
29e20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29e30 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
29e40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29e50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29e60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
29e70 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
29e80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
29e90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
29ea0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
29eb0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
29ec0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
29ed0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
29ee0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
29ef0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
29f00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29f10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
29f20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
29f30 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
29f40 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
29f50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29f60 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
29f70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
29f80 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
29f90 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
29fa0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
29fb0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
29fc0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
29fd0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
29fe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
29ff0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2a000 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2a010 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2a020 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2a030 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2a040 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2a050 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2a060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a070 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a080 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a090 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2a0a0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a0b0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2a0c0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2a0d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a0e0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2a0f0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2a100 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2a110 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2a120 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2a130 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2a140 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2a150 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2a160 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2a170 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2a180 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2a190 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2a1a0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2a1b0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2a1c0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2a1d0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2a1e0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2a1f0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2a200 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2a210 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2a220 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2a230 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2a240 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2a250 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2a260 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2a270 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2a280 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2a290 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2a2a0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2a2b0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2a2c0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2a2d0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2a2e0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2a2f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a300 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2a310 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2a320 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2a330 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2a340 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2a350 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2a360 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2a370 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2a380 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2a390 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2a3a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2a3b0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2a3c0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2a3d0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2a3e0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2a3f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2a400 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2a410 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2a420 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2a430 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2a440 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2a450 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2a460 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2a470 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2a480 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2a490 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2a4a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2a4b0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2a4c0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2a4d0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2a4e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2a4f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2a500 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2a510 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2a520 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2a530 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2a540 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2a550 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2a560 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2a570 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2a580 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2a590 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2a5a0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2a5b0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2a5c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2a5d0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2a5e0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2a5f0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2a600 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2a610 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2a620 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2a630 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2a640 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2a650 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2a660 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2a670 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2a680 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2a690 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2a6a0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2a6b0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2a6c0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2a6d0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2a6e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2a6f0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2a700 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2a710 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2a720 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2a730 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2a740 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2a750 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2a760 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2a770 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2a780 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2a790 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2a7a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a7b0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2a7c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a7d0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2a7e0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2a7f0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2a800 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2a810 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2a820 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2a830 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2a840 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2a850 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2a860 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2a870 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2a880 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2a890 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2a8a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a8b0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2a8c0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2a8d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2a8e0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2a8f0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2a900 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2a910 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2a920 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2a930 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2a940 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2a950 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2a960 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a970 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2a980 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2a990 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2a9a0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2a9b0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2a9c0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2a9d0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2a9e0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2a9f0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2aa00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2aa10 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2aa20 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2aa30 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2aa40 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2aa50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2aa60 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2aa70 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2aa80 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2aa90 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2aaa0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2aab0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2aac0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2aad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2aae0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2aaf0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2ab00 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2ab10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2ab20 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2ab30 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2ab40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ab50 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2ab60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ab70 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2ab80 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2ab90 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2aba0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2abb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2abc0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2abd0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2abe0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2abf0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2ac00 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2ac10 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2ac20 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2ac30 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2ac40 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2ac50 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2ac60 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2ac70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2ac80 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2ac90 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2aca0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2acb0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2acc0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2acd0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2ace0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2acf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2ad00 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2ad10 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2ad20 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2ad30 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2ad40 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2ad50 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2ad60 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2ad70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2ad80 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2ad90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2ada0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2adb0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2adc0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2add0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2ade0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2adf0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2ae00 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2ae10 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2ae20 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2ae30 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2ae40 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2ae50 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2ae60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ae70 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2ae80 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2ae90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2aea0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2aeb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2aec0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2aed0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2aee0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2aef0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2af00 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2af10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2af20 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2af30 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2af40 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2af50 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2af60 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2af70 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2af80 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2af90 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2afa0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2afb0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
2afc0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2afd0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2afe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2aff0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b000 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2b010 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b020 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2b030 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b040 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b050 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2b060 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2b070 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b080 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2b090 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2b0a0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2b0b0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2b0c0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2b0d0 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2b0e0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2b0f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2b100 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2b110 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2b120 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2b130 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2b140 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2b150 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2b160 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b170 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2b180 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2b190 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2b1a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b1b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b1c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2b1d0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2b1e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b1f0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2b200 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2b210 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2b220 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b230 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2b240 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2b250 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2b260 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2b270 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2b280 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2b290 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2b2a0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2b2b0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2b2c0 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2b2d0 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2b2e0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2b2f0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2b300 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2b310 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2b320 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2b330 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b340 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2b350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b360 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2b370 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b390 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2b3a0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2b3b0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2b3c0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2b3d0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2b3e0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2b3f0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2b400 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2b410 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2b420 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2b430 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2b440 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2b450 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2b460 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2b470 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2b480 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2b490 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2b4a0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2b4b0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2b4c0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2b4d0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2b4e0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2b4f0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2b500 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2b510 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2b520 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2b530 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2b540 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2b550 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2b560 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2b570 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2b580 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2b590 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2b5a0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2b5b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b5c0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2b5d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2b5e0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2b5f0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2b600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b610 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2b620 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2b630 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2b640 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2b650 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2b660 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2b670 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2b680 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2b690 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2b6a0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2b6b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2b6c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2b6d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2b6e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2b6f0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2b700 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2b710 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b720 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2b730 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2b740 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2b750 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2b760 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2b770 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2b780 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2b790 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2b7a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2b7b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b7c0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2b7d0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2b7e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2b7f0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2b800 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2b810 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b820 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2b830 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2b840 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2b850 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2b860 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2b870 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2b880 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2b890 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2b8a0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2b8b0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2b8c0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2b8d0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2b8e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2b8f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2b900 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2b910 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2b920 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2b930 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2b940 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2b950 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2b960 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2b970 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2b980 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2b990 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2b9a0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2b9b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2b9c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2b9d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2b9e0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2b9f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2ba00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ba10 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2ba20 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2ba30 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2ba40 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2ba50 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ba60 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2ba70 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2ba80 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2ba90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2baa0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2bab0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bac0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2bad0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2bae0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2baf0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2bb00 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2bb10 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2bb20 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2bb30 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2bb40 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2bb50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2bb60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bb70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2bb80 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2bb90 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2bba0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2bbb0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2bbc0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2bbd0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2bbe0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2bbf0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2bc00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2bc10 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2bc20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2bc30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2bc40 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2bc50 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2bc60 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2bc70 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2bc80 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2bc90 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2bca0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2bcb0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2bcc0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2bcd0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2bce0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2bcf0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2bd00 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2bd10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bd20 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2bd30 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2bd40 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2bd50 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2bd60 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2bd70 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2bd80 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2bd90 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2bda0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2bdb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2bdc0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2bdd0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2bde0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2bdf0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2be00 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2be10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2be20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2be30 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2be40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2be50 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2be60 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2be70 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2be80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2be90 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2bea0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2beb0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2bec0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2bed0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2bee0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2bef0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2bf00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bf10 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2bf20 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2bf30 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2bf40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2bf50 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2bf60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2bf70 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2bf80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bf90 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2bfa0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2bfb0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2bfc0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2bfd0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2bfe0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2bff0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c000 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2c010 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c020 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2c030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c040 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2c050 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2c060 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2c070 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2c080 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c0a0 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2c0b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2c0c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c0d0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2c0e0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2c0f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2c100 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2c110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c120 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2c130 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2c140 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2c150 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2c160 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2c170 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c180 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2c190 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2c1a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c1b0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2c1c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2c1d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2c1e0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2c1f0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2c200 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2c210 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c220 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2c230 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c240 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2c250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c260 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2c270 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2c280 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2c290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c2a0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2c2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c2c0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2c2d0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2c2e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2c2f0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2c300 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2c310 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2c320 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2c330 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2c340 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2c350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2c360 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2c370 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2c380 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2c390 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2c3a0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2c3b0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2c3c0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2c3d0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2c3e0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2c3f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c400 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2c410 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2c420 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2c430 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2c440 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2c450 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2c460 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2c470 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2c480 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2c490 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2c4a0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c4c0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2c4d0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2c4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c4f0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2c500 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c510 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2c520 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2c530 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2c540 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2c550 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c560 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2c570 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2c580 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c590 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c5a0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c5b0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c5c0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2c5d0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2c5e0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2c5f0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2c600 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2c610 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2c620 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2c630 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2c640 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2c650 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2c660 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c670 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c680 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2c690 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2c6a0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2c6b0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2c6c0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2c6d0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2c6e0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2c6f0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2c700 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2c710 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2c720 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2c730 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2c740 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2c750 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2c760 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2c770 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2c780 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2c790 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2c7a0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2c7b0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2c7c0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2c7d0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2c7e0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2c7f0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2c800 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2c810 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2c820 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2c830 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2c840 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2c850 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2c860 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2c870 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2c880 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2c890 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2c8a0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2c8b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2c8c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2c8d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2c8e0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2c8f0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2c900 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2c910 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2c920 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2c930 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2c940 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2c950 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2c960 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2c970 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2c980 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2c990 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2c9a0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2c9b0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2c9c0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2c9d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2c9e0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2c9f0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2ca00 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2ca10 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2ca20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2ca30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ca40 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2ca50 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2ca60 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2ca70 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ca80 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2ca90 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2caa0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2cab0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cac0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2cad0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2cae0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2caf0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2cb00 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2cb10 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2cb20 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2cb30 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2cb40 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2cb50 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2cb60 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2cb70 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2cb80 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2cb90 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2cba0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2cbb0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2cbc0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2cbd0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2cbe0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2cbf0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2cc00 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2cc10 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2cc20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2cc30 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2cc40 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2cc50 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2cc60 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2cc70 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2cc80 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2cc90 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2cca0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2ccb0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2ccc0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2ccd0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2cce0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2ccf0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2cd00 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2cd10 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2cd20 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2cd30 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2cd40 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2cd50 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2cd60 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2cd70 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2cd80 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2cd90 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2cda0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2cdb0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2cdc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2cdd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2cde0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2cdf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ce00 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2ce10 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2ce20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2ce30 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2ce40 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2ce50 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2ce60 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2ce70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2ce80 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2ce90 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2cea0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ceb0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2cec0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2ced0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2cee0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2cef0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2cf00 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2cf10 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2cf20 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2cf30 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2cf40 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2cf50 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2cf60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cf70 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2cf80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf90 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2cfa0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2cfb0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2cfc0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2cfd0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2cfe0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2cff0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2d000 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2d010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d020 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2d030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d040 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2d050 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2d060 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2d070 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2d080 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2d090 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2d0a0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2d0b0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2d0c0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2d0d0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2d0e0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2d0f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2d100 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2d110 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d120 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2d130 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2d140 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2d150 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2d160 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2d170 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2d180 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2d190 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2d1a0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2d1b0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2d1c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2d1d0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2d1e0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2d1f0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2d200 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2d210 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2d220 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2d230 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2d240 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2d250 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2d260 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2d270 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2d280 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2d290 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2d2a0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2d2b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d2c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2d2d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d2e0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2d2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d300 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2d310 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2d320 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2d330 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2d340 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d350 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2d360 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2d370 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2d380 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2d390 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2d3a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d3b0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2d3c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d3d0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2d3e0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2d3f0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2d400 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2d410 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2d420 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2d430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d440 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2d450 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2d460 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2d470 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2d480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d490 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2d4a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2d4b0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2d4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d4d0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2d4e0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2d4f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2d500 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2d510 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2d520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d530 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2d540 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2d550 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2d560 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d570 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2d580 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2d590 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2d5a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2d5b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d5c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2d5d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2d5e0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2d5f0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2d600 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2d610 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2d620 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2d630 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2d640 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2d650 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2d660 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d670 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2d680 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2d690 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2d6a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2d6b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2d6c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d6d0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2d6e0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2d6f0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2d700 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2d710 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2d720 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2d730 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2d740 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2d750 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2d760 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2d770 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2d780 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2d790 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2d7a0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2d7b0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2d7c0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2d7d0 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
2d7e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d7f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2d800 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d810 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2d820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d830 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d840 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2d850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d860 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2d870 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d880 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2d890 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2d8a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d8b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2d8c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2d8d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d8e0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2d8f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2d900 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2d910 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d920 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
2d930 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2d940 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2d950 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d960 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
2d970 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d980 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
2d990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d9a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2d9b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2d9c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d9d0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
2d9e0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2d9f0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2da00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2da10 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2da20 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2da30 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2da40 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2da50 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2da60 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2da70 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2da80 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2da90 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2daa0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2dab0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2dac0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2dad0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2dae0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2daf0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2db00 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2db10 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2db20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2db30 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2db40 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2db50 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2db60 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2db70 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2db80 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2db90 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2dba0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2dbb0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2dbc0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2dbd0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2dbe0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2dbf0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2dc00 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2dc10 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2dc20 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2dc30 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2dc40 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2dc50 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2dc60 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2dc70 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2dc80 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2dc90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2dca0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2dcb0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2dcc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2dcd0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2dce0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2dcf0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2dd00 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2dd10 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2dd20 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2dd30 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2dd40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2dd50 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2dd60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2dd70 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2dd80 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2dd90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dda0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
2ddb0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
2ddc0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
2ddd0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
2dde0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2ddf0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
2de00 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
2de10 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2de20 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2de30 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
2de40 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
2de50 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2de60 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2de70 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
2de80 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
2de90 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
2dea0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
2deb0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
2dec0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
2ded0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2dee0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2def0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2df00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2df10 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2df20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2df30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2df40 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2df50 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2df60 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2df70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2df80 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2df90 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2dfa0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2dfb0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2dfc0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2dfd0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2dfe0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2dff0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2e000 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2e010 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2e020 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2e030 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2e040 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2e050 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2e060 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2e070 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2e090 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2e0a0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2e0b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e0c0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2e0d0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2e0e0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2e0f0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2e100 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e110 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2e120 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2e130 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e140 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2e150 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2e160 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2e170 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2e180 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2e190 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2e1a0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2e1b0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
2e1c0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2e1d0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2e1e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2e1f0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2e200 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2e210 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2e220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e230 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2e240 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2e250 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e260 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
2e270 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2e280 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2e290 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2e2a0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2e2b0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2e2c0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
2e2d0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2e2e0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2e2f0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2e300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2e310 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e320 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2e330 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e340 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2e350 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2e360 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2e370 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2e380 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2e390 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2e3a0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2e3b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e3c0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2e3d0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2e3e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e3f0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2e400 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2e410 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2e420 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2e430 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2e440 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2e450 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2e460 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2e470 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2e480 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2e490 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2e4a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2e4b0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2e4c0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2e4d0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2e4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e4f0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2e500 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2e510 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2e520 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2e530 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2e540 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2e550 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2e560 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2e570 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2e580 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2e590 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2e5a0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2e5b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2e5c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e5d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e5e0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2e5f0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2e600 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2e610 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2e620 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2e630 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2e640 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2e650 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2e660 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2e670 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2e680 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2e690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e6a0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2e6b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2e6c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2e6d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e6e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2e6f0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2e700 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2e710 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2e720 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2e730 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2e740 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2e750 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2e760 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2e770 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2e780 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2e790 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2e7a0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2e7b0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2e7c0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2e7d0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2e7e0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2e7f0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2e800 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2e810 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2e820 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2e830 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2e840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2e850 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2e860 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2e870 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2e880 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2e890 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2e8a0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2e8b0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2e8c0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2e8d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2e8e0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2e8f0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2e900 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2e910 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2e920 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2e930 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2e940 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2e950 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2e960 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2e970 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2e980 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2e990 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2e9a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2e9b0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2e9c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2e9d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2e9e0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2e9f0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2ea00 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2ea10 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2ea20 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2ea30 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2ea40 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2ea50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2ea60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2ea70 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2ea80 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2ea90 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2eaa0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2eab0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2eac0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2ead0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2eae0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2eaf0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2eb00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2eb10 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2eb20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2eb30 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2eb40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2eb50 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2eb60 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2eb70 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2eb80 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2eb90 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2eba0 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2ebb0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2ebc0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2ebd0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2ebe0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2ebf0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2ec00 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2ec10 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2ec20 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2ec30 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2ec40 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2ec50 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2ec60 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2ec70 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2ec80 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2ec90 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2eca0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2ecb0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2ecc0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2ecd0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2ece0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2ecf0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2ed00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ed10 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2ed20 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2ed30 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2ed40 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2ed50 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2ed60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2ed70 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2ed80 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2ed90 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2eda0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2edb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2edc0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2edd0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2ede0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2edf0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2ee00 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2ee10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2ee20 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2ee30 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2ee40 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2ee50 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2ee60 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2ee70 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2ee80 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2ee90 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2eea0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2eeb0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2eec0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2eed0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2eee0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2eef0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2ef00 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2ef10 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2ef20 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2ef30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2ef40 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2ef50 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2ef60 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2ef70 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2ef80 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2ef90 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2efa0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2efb0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2efc0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2efd0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2efe0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2eff0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2f000 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2f010 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2f020 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2f030 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2f040 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2f050 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2f060 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2f070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f080 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2f090 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2f0a0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2f0b0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2f0c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f0d0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2f0e0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2f0f0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2f100 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2f110 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2f120 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2f130 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2f140 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2f150 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2f160 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f170 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2f180 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2f190 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f1a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f1b0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2f1c0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2f1d0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2f1e0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f1f0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f200 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2f210 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2f220 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2f230 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2f240 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2f250 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2f260 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2f270 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2f280 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2f290 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2f2a0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2f2b0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2f2c0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2f2d0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2f2e0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2f2f0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2f300 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2f310 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2f320 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2f330 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2f340 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2f350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f360 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2f370 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2f380 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2f390 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2f3a0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2f3b0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2f3c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2f3d0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2f3e0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2f3f0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2f400 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2f410 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2f420 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2f430 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2f440 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2f450 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2f460 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2f470 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2f480 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2f490 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2f4a0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2f4b0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2f4c0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2f4d0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2f4e0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2f4f0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2f500 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2f510 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2f520 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f530 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2f540 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2f550 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2f560 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2f570 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2f580 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2f590 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f5a0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2f5b0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2f5c0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2f5d0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2f5e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2f5f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
2f600 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f610 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2f620 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f630 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f640 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f650 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f660 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f670 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f690 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f6a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f6b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f6c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f6d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f6e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f700 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2f710 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f720 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2f730 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2f740 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2f750 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2f760 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2f770 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2f780 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2f790 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2f7a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2f7b0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2f7c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f7d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f7e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f7f0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2f800 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2f810 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f820 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
2f830 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2f840 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2f850 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2f860 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2f870 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2f880 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2f890 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2f8a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2f8b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2f8c0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2f8d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f8f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2f900 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f910 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
2f920 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2f930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f940 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
2f950 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2f960 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2f970 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2f980 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2f990 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2f9a0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2f9b0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2f9c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2f9d0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2f9e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2f9f0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2fa00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fa10 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2fa20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fa30 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2fa40 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2fa50 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2fa60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2fa70 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2fa80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2fa90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2faa0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2fab0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2fac0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2fad0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2fae0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2faf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
2fb00 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
2fb10 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
2fb20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2fb30 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
2fb40 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
2fb50 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2fb60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2fb70 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2fb80 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
2fb90 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
2fba0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
2fbb0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
2fbc0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
2fbd0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
2fbe0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
2fbf0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2fc00 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
2fc10 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
2fc20 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
2fc30 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
2fc40 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
2fc50 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
2fc60 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
2fc70 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
2fc80 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
2fc90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2fca0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fcb0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2fcc0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
2fcd0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2fce0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2fcf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2fd00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fd10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
2fd20 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2fd30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2fd40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2fd50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2fd60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
2fd70 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2fd80 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2fd90 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
2fda0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2fdb0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2fdc0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2fdd0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2fde0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2fdf0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2fe00 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2fe10 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
2fe20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fe30 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
2fe40 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
2fe50 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
2fe60 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
2fe70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2fe80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2fe90 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
2fea0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
2feb0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
2fec0 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
2fed0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
2fee0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
2fef0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ff00 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
2ff10 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
2ff20 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
2ff30 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
2ff40 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
2ff50 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2ff60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ff70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ff80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ff90 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
2ffa0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
2ffb0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2ffc0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2ffd0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
2ffe0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2fff0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
30000 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
30010 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
30020 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30030 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30040 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
30050 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30060 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
30070 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
30080 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30090 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
300a0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
300b0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
300c0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
300d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
300e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
300f0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
30100 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
30110 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30120 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
30130 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
30140 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
30150 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
30160 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30170 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
30180 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
30190 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
301a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
301b0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
301c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
301d0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
301e0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
301f0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
30200 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
30210 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
30220 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30230 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
30240 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
30250 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
30260 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
30270 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
30280 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
30290 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
302a0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
302b0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
302c0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
302d0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
302e0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
302f0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
30300 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
30310 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
30320 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
30330 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
30340 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
30350 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
30360 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
30370 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
30380 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
30390 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
303a0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
303b0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
303c0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
303d0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
303e0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
303f0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
30400 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
30410 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
30420 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
30430 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
30440 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
30450 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
30460 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
30470 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
30480 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
30490 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
304a0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
304b0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
304c0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
304d0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
304e0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
304f0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
30500 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
30510 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
30520 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
30530 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
30540 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
30550 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
30560 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
30570 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
30580 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
30590 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
305a0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
305b0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
305c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
305d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
305e0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
305f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30600 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
30610 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
30620 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
30630 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
30640 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
30650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30660 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
30670 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
30680 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
30690 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
306a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
306b0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
306c0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
306d0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
306e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
306f0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
30700 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30710 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
30720 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
30730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
30740 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
30750 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
30760 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
30770 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
30780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30790 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
307a0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
307b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
307c0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
307d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
307e0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
307f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
30800 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
30810 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
30820 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30830 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30840 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
30850 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
30860 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
30870 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
30880 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30890 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
308a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
308b0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
308c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
308d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
308e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
308f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
30910 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
30920 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
30930 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
30940 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
30950 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
30960 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
30970 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
30980 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
30990 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
309a0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
309b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
309c0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
309d0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
309e0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
309f0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
30a00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
30a10 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
30a20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30a30 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
30a40 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
30a50 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
30a60 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
30a70 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
30a80 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
30a90 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
30aa0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
30ab0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
30ac0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
30ad0 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
30ae0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
30af0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
30b00 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30b10 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
30b20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
30b30 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
30b40 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
30b50 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
30b60 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
30b70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
30b80 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
30b90 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
30ba0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
30bb0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
30bc0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
30bd0 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
30be0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
30bf0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
30c00 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
30c10 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
30c20 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
30c30 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
30c40 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
30c50 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
30c60 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30c70 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
30c80 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
30c90 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
30ca0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
30cb0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
30cc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30cd0 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
30ce0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
30cf0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
30d00 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
30d10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
30d20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30d30 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
30d40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
30d50 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
30d60 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
30d70 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
30d80 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
30d90 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
30da0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
30db0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
30dc0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
30dd0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30de0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
30df0 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
30e00 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
30e10 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
30e20 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
30e30 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
30e40 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
30e50 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
30e60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30e70 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
30e80 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
30e90 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
30ea0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
30eb0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
30ec0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
30ed0 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
30ee0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
30ef0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
30f00 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
30f10 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
30f20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
30f30 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
30f40 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
30f50 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
30f60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
30f70 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
30f80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
30f90 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
30fa0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
30fb0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
30fc0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
30fd0 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
30fe0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
30ff0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
31000 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
31010 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
31020 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
31030 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
31040 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31050 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
31060 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
31070 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
31080 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
31090 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
310a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
310b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
310c0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
310d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
310e0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
310f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
31100 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
31110 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
31120 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
31130 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
31140 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
31150 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
31160 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
31170 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
31180 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31190 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
311a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
311b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
311c0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
311d0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
311e0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
311f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
31200 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
31210 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
31220 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31230 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31240 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31250 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31260 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31270 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
31280 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
31290 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
312a0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
312b0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
312c0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
312d0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
312e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
312f0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
31300 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
31310 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
31320 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
31330 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31340 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
31350 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
31360 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
31370 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31380 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
31390 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
313a0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
313b0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
313c0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
313d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
313e0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
313f0 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
31400 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
31410 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
31420 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
31430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
31440 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
31450 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
31460 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
31470 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
31480 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
31490 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
314a0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
314b0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
314c0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
314d0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
314e0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
314f0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
31500 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
31510 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
31520 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
31530 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
31540 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
31550 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
31560 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
31570 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
31580 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
31590 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
315a0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
315b0 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
315c0 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
315d0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
315e0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
315f0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
31600 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
31610 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
31620 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
31630 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
31640 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
31650 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
31660 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
31670 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
31680 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
31690 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
316a0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
316b0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
316c0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
316d0 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
316e0 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
316f0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
31700 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
31710 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
31720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31730 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31740 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31750 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
31760 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
31770 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
31780 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31790 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
317a0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
317b0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
317c0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
317d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
317e0 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
317f0 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
31800 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
31810 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
31820 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
31830 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
31840 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
31850 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
31860 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
31870 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
31880 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
31890 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
318a0 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
318b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
318c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
318d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
318e0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
318f0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
31900 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
31910 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
31920 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
31930 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
31940 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
31950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31960 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
31970 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
31980 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31990 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
319a0 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
319b0 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
319c0 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
319d0 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
319e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
319f0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
31a00 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
31a10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
31a20 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
31a30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31a40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
31a50 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
31a60 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
31a70 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
31a80 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
31a90 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
31aa0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
31ab0 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
31ac0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
31ad0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
31ae0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
31af0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31b00 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
31b10 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
31b20 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
31b30 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
31b40 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
31b50 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
31b60 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
31b70 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
31b80 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
31b90 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
31ba0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
31bb0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
31bc0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
31bd0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
31be0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
31bf0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
31c00 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
31c10 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
31c20 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
31c30 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
31c40 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
31c50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
31c60 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
31c70 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
31c80 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
31c90 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
31ca0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
31cb0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
31cc0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
31cd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31ce0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
31cf0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
31d00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31d10 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
31d20 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
31d30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
31d40 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
31d50 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
31d60 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
31d70 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
31d80 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
31d90 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
31da0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
31db0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
31dc0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
31dd0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
31de0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31df0 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
31e00 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
31e10 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
31e20 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
31e30 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
31e40 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
31e50 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
31e60 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
31e70 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
31e80 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
31e90 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
31ea0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
31eb0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
31ec0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
31ed0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
31ee0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
31ef0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
31f00 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
31f10 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
31f20 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
31f30 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
31f40 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
31f50 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
31f60 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
31f70 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
31f80 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
31f90 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
31fa0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
31fb0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
31fc0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
31fd0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
31fe0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
31ff0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
32000 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
32010 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
32020 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
32030 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
32040 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32050 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
32060 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
32070 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
32080 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
32090 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
320a0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
320b0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
320c0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
320d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
320e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
320f0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
32100 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32110 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
32120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
32130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32140 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
32150 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
32160 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32170 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
32180 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
32190 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
321a0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
321b0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
321c0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
321d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
321e0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
321f0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
32200 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
32210 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
32220 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
32230 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
32240 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
32250 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32260 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
32270 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
32280 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
32290 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
322a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
322b0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
322c0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
322d0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
322e0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
322f0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
32300 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
32310 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
32320 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
32330 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32340 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
32350 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
32360 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
32370 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32380 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32390 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
323a0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
323b0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
323c0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
323d0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
323e0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
323f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
32400 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32410 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
32420 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32430 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
32440 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32450 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32460 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
32470 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
32480 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
32490 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
324a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
324b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
324c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
324d0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
324e0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
324f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
32500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
32510 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
32520 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
32530 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
32540 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
32550 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
32560 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
32570 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
32580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32590 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
325a0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
325b0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
325c0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
325d0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
325e0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
325f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32600 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
32610 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
32620 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
32630 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
32640 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
32650 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
32660 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
32670 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
32680 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
32690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
326a0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
326b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
326c0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
326d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
326e0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
326f0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
32700 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
32710 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
32720 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
32730 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
32740 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
32750 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
32760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32770 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
32780 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
32790 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
327a0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
327b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
327c0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
327d0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
327e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
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 28 29 20 61  result_error() a
32810 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
32820 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
32830 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
32840 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
32850 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
32860 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
32870 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
32880 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
32890 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
328a0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
328b0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
328c0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
328d0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
328e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
328f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
32900 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
32910 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
32920 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
32930 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
32940 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
32950 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
32960 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
32970 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
32980 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
32990 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
329a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
329b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
329c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
329d0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
329e0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
329f0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
32a00 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
32a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32a20 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
32a30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
32a40 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
32a50 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
32a60 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
32a70 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
32a80 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
32a90 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
32aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32ab0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
32ac0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
32ad0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
32ae0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
32af0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
32b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
32b10 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
32b20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32b30 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
32b40 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
32b50 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
32b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32b70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32b80 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
32b90 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
32ba0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
32bb0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
32bc0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
32bd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
32be0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32bf0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32c00 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
32c10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32c20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
32c30 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
32c40 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
32c50 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
32c60 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
32c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32c80 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
32c90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32ca0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32cb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32cc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32cd0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
32ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32cf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
32d00 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
32d10 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
32d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32d30 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
32d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32d50 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
32d60 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
32d70 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
32d80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32d90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32da0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
32db0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
32dc0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
32dd0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
32de0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
32df0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
32e00 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
32e10 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
32e20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
32e30 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
32e40 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
32e50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32e60 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
32e70 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
32e80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32e90 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
32ea0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
32eb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
32ec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32ed0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
32ee0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
32ef0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
32f00 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
32f10 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
32f20 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
32f30 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
32f40 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
32f50 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
32f60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
32f70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32f80 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
32f90 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
32fa0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
32fb0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
32fc0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
32fd0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
32fe0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
32ff0 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
33000 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33010 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
33020 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
33030 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
33040 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
33050 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
33060 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
33070 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
33080 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
33090 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
330a0 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
330b0 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
330c0 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
330d0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
330e0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
330f0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
33100 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
33110 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
33120 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
33130 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
33140 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
33150 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
33160 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
33170 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
33180 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
33190 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
331a0 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
331b0 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
331c0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
331d0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
331e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
331f0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33200 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33210 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
33220 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
33230 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
33240 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
33250 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
33260 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
33270 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
33280 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
33290 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
332a0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
332b0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
332c0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
332d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
332e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
332f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
33300 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
33310 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
33320 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
33330 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
33340 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
33350 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
33360 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
33370 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
33380 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
33390 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
333a0 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
333b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
333c0 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
333d0 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
333e0 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
333f0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
33400 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
33410 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
33420 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
33430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33440 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33450 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33460 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
33470 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
33480 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
33490 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
334a0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
334b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
334c0 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
334d0 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
334e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
334f0 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
33500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
33510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
33520 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
33530 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
33540 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
33550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33560 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
33570 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
33580 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33590 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
335a0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
335b0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
335c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
335d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
335e0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
335f0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
33600 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
33610 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
33620 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
33630 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
33640 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
33650 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
33660 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
33670 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33680 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
33690 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
336a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
336b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
336c0 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
336d0 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
336e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
336f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33700 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
33710 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
33720 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
33730 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
33740 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
33750 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
33760 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
33770 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
33780 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
33790 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
337a0 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
337b0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
337c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
337d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
337e0 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
337f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
33800 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
33810 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
33820 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
33830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33840 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
33850 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33860 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33870 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33880 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
33890 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
338a0 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
338b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
338c0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
338d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
338e0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
338f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33900 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
33910 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33920 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
33930 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33940 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
33950 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33960 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33970 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
33980 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33990 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
339a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
339b0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
339c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
339d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
339e0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
339f0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
33a00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33a10 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
33a20 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
33a30 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
33a40 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
33a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33a60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33a70 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
33a80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33a90 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
33aa0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33ab0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33ac0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
33ad0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33ae0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33af0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33b00 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33b10 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
33b20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33b30 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33b40 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
33b50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33b60 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
33b70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33b80 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33b90 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
33ba0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33bb0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
33bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
33bd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33be0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33bf0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
33c00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33c10 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
33c20 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
33c30 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
33c40 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
33c50 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
33c60 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
33c70 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
33c80 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
33c90 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
33ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33cb0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
33cc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
33cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
33ce0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
33cf0 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
33d00 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
33d10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33d20 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
33d30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33d40 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
33d50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
33d60 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
33d70 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
33d80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33d90 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
33da0 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
33db0 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
33dc0 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
33dd0 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
33de0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
33df0 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
33e00 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
33e10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
33e20 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
33e30 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
33e40 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
33e50 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
33e60 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
33e70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
33e80 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
33e90 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
33ea0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
33eb0 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
33ec0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
33ed0 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
33ee0 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
33ef0 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
33f00 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
33f10 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
33f20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
33f30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33f40 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
33f50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
33f60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
33f70 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
33f80 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
33f90 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
33fa0 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
33fb0 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
33fc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33fd0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
33fe0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
33ff0 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
34000 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
34010 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
34020 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
34030 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
34040 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
34050 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
34060 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
34070 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
34080 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
34090 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
340a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to 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 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
340d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
340e0 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
340f0 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
34100 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
34110 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
34120 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
34130 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
34140 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
34150 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
34160 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
34170 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
34180 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
34190 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
341a0 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
341b0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
341c0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
341d0 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
341e0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
341f0 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
34200 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
34210 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
34220 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
34230 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
34240 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
34250 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
34260 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
34270 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
34280 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
34290 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
342a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
342b0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
342c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
342d0 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
342e0 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
342f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34300 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
34310 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
34320 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
34330 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
34340 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
34350 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
34360 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34370 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
34380 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
34390 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
343a0 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
343b0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
343c0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
343d0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
343e0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
343f0 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
34400 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
34410 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34420 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
34430 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
34440 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
34450 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
34460 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
34470 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
34480 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
34490 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
344a0 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
344b0 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
344c0 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
344d0 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
344e0 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
344f0 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
34500 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
34510 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
34520 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
34530 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
34540 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
34550 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
34560 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
34570 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
34580 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
34590 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
345a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
345b0 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
345c0 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
345d0 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
345e0 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
345f0 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
34600 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
34610 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
34620 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
34630 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
34640 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
34650 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
34660 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
34670 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
34680 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
34690 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
346a0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
346b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
346c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
346d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
346e0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
346f0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
34700 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
34710 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
34720 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
34730 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
34740 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
34750 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
34760 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34770 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
34780 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34790 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
347a0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
347b0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
347c0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
347d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
347e0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
347f0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
34800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34810 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
34820 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
34830 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
34840 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
34850 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
34860 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
34870 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
34880 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
34890 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
348a0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
348b0 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
348c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
348d0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
348e0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
348f0 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
34900 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
34910 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
34920 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
34930 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34940 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
34950 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
34960 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
34970 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
34980 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
34990 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
349a0 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
349b0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
349c0 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
349d0 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
349e0 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
349f0 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
34a00 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
34a10 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
34a20 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
34a30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34a40 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
34a50 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
34a60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
34a70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34a80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
34a90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34aa0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
34ab0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
34ac0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
34ad0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34ae0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34af0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34b00 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34b10 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
34b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
34b30 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34b40 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
34b50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
34b60 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
34b70 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
34b80 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
34b90 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34ba0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34bb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
34bc0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
34bd0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
34be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34bf0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
34c00 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
34c10 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
34c20 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
34c30 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
34c40 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
34c50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34c60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34c70 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
34c80 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
34c90 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
34ca0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
34cb0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
34cc0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
34cd0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
34ce0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
34cf0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
34d00 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
34d10 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
34d20 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
34d30 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
34d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
34d50 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
34d60 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
34d70 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
34d80 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
34d90 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
34da0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
34db0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
34dc0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
34dd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
34de0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
34df0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
34e00 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
34e10 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
34e20 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
34e30 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
34e40 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
34e50 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34e60 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
34e70 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
34e80 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
34e90 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
34ea0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
34eb0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
34ec0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
34ed0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
34ee0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
34ef0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
34f00 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
34f10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
34f20 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
34f30 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
34f40 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
34f50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
34f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
34f70 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
34f80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
34f90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34fa0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
34fb0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
34fc0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
34fd0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
34fe0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
34ff0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
35000 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
35010 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
35020 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
35030 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
35040 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
35050 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35060 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
35070 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
35080 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
35090 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
350a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
350b0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
350c0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
350d0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
350e0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
350f0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
35100 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
35110 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
35120 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35130 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35140 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35150 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
35160 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35170 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
35180 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
35190 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
351a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
351b0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
351c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
351d0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
351e0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
351f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35200 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
35210 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
35220 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
35230 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
35240 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
35250 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
35260 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
35270 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
35280 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
35290 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
352a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
352b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
352c0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
352d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
352e0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
352f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35300 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35310 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35320 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35330 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
35340 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
35350 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35360 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35370 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35380 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35390 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
353a0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
353b0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
353c0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
353d0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
353e0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
353f0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
35400 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
35410 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
35420 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
35430 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
35440 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
35450 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
35460 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
35470 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
35480 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
35490 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
354a0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
354b0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
354c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
354d0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
354e0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
354f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
35500 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
35510 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
35520 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
35530 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
35540 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
35550 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
35560 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
35570 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
35580 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
35590 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
355a0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
355b0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
355c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
355d0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
355e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
355f0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
35600 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
35610 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
35620 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
35630 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
35640 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
35650 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
35660 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
35670 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
35680 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
35690 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
356a0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
356b0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
356c0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
356d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
356e0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
356f0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
35700 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
35710 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
35720 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
35730 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
35740 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
35750 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35760 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
35770 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35780 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
35790 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
357a0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
357b0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
357c0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
357d0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
357e0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
357f0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
35800 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
35810 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
35820 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
35830 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
35840 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
35850 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
35860 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
35870 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
35880 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35890 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
358a0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
358b0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
358c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
358d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
358e0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
358f0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
35900 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
35910 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
35920 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
35930 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
35940 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
35950 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
35960 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
35970 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
35980 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
35990 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
359a0 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
359b0 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
359c0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
359d0 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
359e0 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
359f0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
35a00 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
35a10 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74  ragraphs..*/.int
35a20 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
35a30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
35a40 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
35a50 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
35a60 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
35a70 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
35a80 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35a90 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35aa0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35ab0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35ac0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35ad0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
35ae0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
35af0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
35b00 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
35b10 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
35b20 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
35b30 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
35b40 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
35b50 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
35b60 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
35b70 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
35b80 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35b90 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35ba0 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35bb0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
35bc0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
35bd0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
35be0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35bf0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
35c00 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
35c10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
35c20 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
35c30 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
35c40 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35c50 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35c60 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
35c70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35c80 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
35c90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
35ca0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
35cb0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
35cc0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
35cd0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
35ce0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
35cf0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
35d00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
35d10 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
35d20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
35d30 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
35d40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
35d50 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35d60 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
35d70 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
35d80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
35d90 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35da0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
35db0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35dc0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
35dd0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
35de0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
35df0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35e00 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
35e10 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
35e20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35e30 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
35e40 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
35e50 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
35e60 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
35e70 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
35e80 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
35e90 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
35ea0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
35eb0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
35ec0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
35ed0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
35ee0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
35ef0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
35f00 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
35f10 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
35f20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
35f30 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
35f40 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
35f50 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
35f60 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
35f70 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
35f80 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
35f90 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
35fa0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35fb0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
35fc0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
35fd0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
35fe0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
35ff0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
36000 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
36010 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
36020 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
36030 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ling [sqlite3_op
36040 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  en] or [sqlite3_
36050 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72  open_v2].  Other
36060 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
36070 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
36080 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
36090 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
360a0 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72  s may fail.  Her
360b0 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70  e is an.** examp
360c0 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20  le of how to do 
360d0 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77  this using C++ w
360e0 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20  ith the Windows 
360f0 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c  Runtime:.**.** <
36100 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
36110 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74  .** LPCWSTR zPat
36120 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f  h = Windows::Sto
36130 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f  rage::Applicatio
36140 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e  nData::Current->
36150 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54  .** &nbsp;     T
36160 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e  emporaryFolder->
36170 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a  Path->Data();.**
36180 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23   char zPathBuf&#
36190 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26  91;MAX_PATH + 1&
361a0 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28  #93;;.** memset(
361b0 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a  zPathBuf, 0, siz
361c0 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a  eof(zPathBuf));.
361d0 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c  ** WideCharToMul
361e0 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20  tiByte(CP_UTF8, 
361f0 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50  0, zPath, -1, zP
36200 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a  athBuf, sizeof(z
36210 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62  PathBuf),.** &nb
36220 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55  sp;     NULL, NU
36230 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  LL);.** sqlite3_
36240 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d  temp_directory =
36250 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
36260 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29  ("%s", zPathBuf)
36270 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
36280 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49  ckquote>.*/.SQLI
36290 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
362a0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
362b0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
362c0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
362d0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
362e0 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c  ing Database Fil
362f0 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
36300 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
36310 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
36320 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
36330 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
36340 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
36350 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
36360 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61  ry), then all da
36370 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20  tabase files.** 
36380 73 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61  specified with a
36390 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
363a0 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f  me and created o
363b0 72 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a  r accessed by.**
363c0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
363d0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69  ng a built-in wi
363e0 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76  ndows [sqlite3_v
363f0 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62  fs | VFS] will b
36400 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20  e assumed.** to 
36410 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74  be relative to t
36420 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
36430 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
36440 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le is a NULL.** 
36450 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
36460 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
36470 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66  t all database f
36480 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a  iles specified.*
36490 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76  * with a relativ
364a0 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72  e pathname are r
364b0 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63  elative to the c
364c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
364d0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63  .** for the proc
364e0 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77  ess.  Only the w
364f0 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73  indows VFS makes
36500 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f   use of this glo
36510 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b  bal.** variable;
36520 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62   it is ignored b
36530 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a  y the unix VFS..
36540 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74  **.** Changing t
36550 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  he value of this
36560 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20   variable while 
36570 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
36580 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e  ction is.** open
36590 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61   can result in a
365a0 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73   corrupt databas
365b0 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  e..**.** It is n
365c0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
365d0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
365e0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
365f0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
36600 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
36610 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36620 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36630 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
36640 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
36650 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
36660 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
36670 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
36680 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
36690 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
366a0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
366b0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
366c0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
366d0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
366e0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
366f0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
36700 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
36710 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
36720 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
36730 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
36740 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
36750 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
36760 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73  .** ^The [data_s
36770 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36780 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
36790 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
367a0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
367b0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
367c0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
367d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
367e0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
367f0 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73  ,.** the [data_s
36800 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36810 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
36820 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
36830 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
36840 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
36850 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
36860 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36870 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
36880 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
36890 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
368a0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
368b0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
368c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
368d0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
368e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
368f0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
36900 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
36910 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
36920 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
36930 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
36940 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
36960 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
36970 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73  e of the [data_s
36980 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36990 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
369a0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
369b0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
369c0 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69  *sqlite3_data_di
369d0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
369e0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
369f0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
36a00 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
36a10 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
36a20 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
36a30 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
36a40 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
36a50 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
36a60 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
36a70 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
36a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36a90 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
36aa0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
36ab0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
36ac0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
36ad0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
36ae0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
36af0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
36b00 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
36b10 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
36b20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
36b30 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
36b40 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
36b50 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
36b60 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
36b70 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
36b80 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
36b90 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
36ba0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
36bb0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
36bc0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
36bd0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
36be0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
36bf0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
36c00 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
36c10 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
36c20 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
36c30 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
36c40 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
36c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
36c60 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
36c70 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
36c80 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
36c90 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
36ca0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
36cb0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
36cc0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
36cd0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
36ce0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
36cf0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
36d00 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
36d10 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
36d20 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
36d30 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
36d40 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
36d50 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
36d60 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
36d70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
36d80 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
36d90 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
36da0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36db0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
36dc0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
36dd0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
36de0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
36df0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
36e00 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
36e10 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
36e20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
36e30 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
36e40 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
36e50 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
36e60 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
36e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
36e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
36e90 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
36ea0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
36eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36ec0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
36ed0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
36ee0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
36ef0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
36f00 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
36f10 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
36f20 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
36f30 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
36f40 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
36f50 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
36f60 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
36f70 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
36f80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36f90 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
36fa0 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
36fb0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
36fc0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
36fd0 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
36fe0 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
36ff0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37000 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
37010 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
37020 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
37030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
37040 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
37050 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
37060 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
37070 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
37080 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37090 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
370a0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
370b0 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
370c0 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
370d0 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
370e0 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
370f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
37100 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
37110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
37120 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
37130 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
37140 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
37150 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
37160 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
37170 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
37180 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
37190 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
371a0 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
371b0 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
371c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
371d0 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
371e0 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
371f0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
37200 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
37210 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  name..*/.const c
37220 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  har *sqlite3_db_
37230 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33  filename(sqlite3
37240 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
37250 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
37260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
37270 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61  ermine if a data
37280 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c  base is read-onl
37290 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
372a0 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
372b0 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
372c0 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65  returns 1 if the
372d0 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f   database N.** o
372e0 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69  f connection D i
372f0 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69  s read-only, 0 i
37300 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69  f it is read/wri
37310 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69  te, or -1 if N i
37320 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d  s not.** the nam
37330 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  e of a database 
37340 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  on connection D.
37350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37360 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  db_readonly(sqli
37370 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63  te3 *db, const c
37380 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a  har *zDbName);..
37390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
373a0 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
373b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
373c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
373d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
373e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
373f0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
37400 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
37410 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
37420 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
37430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37440 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74  n] pDb.  ^If pSt
37450 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
37460 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
37470 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
37480 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
37490 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
374a0 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
374b0 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
374c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
374d0 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70  Db.  ^If no prep
374e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
374f0 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
37500 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
37510 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
37520 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
37530 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  ** The [database
37540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
37550 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
37560 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
37570 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
37580 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
37590 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
375a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  * connection and
375b0 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
375c0 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
375d0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
375e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
375f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
37600 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
37610 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
37620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37630 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
37640 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
37650 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
37660 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37670 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
37680 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
37690 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
376a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
376b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
376c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
376d0 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
376e0 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
376f0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
37700 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
37710 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
37720 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
37730 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37750 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
37760 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
37770 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
37780 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
37790 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
377a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
377b0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
377c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
377d0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
377e0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
377f0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37800 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37810 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
37820 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
37830 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
37840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37850 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
37860 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
37870 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
37880 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
37890 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
378a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
378b0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
378c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
378d0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
378e0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
378f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
37900 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
37910 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
37920 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
37930 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
37940 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
37950 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
37960 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
37970 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
37980 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
37990 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
379a0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
379b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
379c0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
379d0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
379e0 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
379f0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
37a00 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e  ** The commit an
37a10 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  d rollback hook 
37a20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f  callbacks are no
37a30 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20  t reentrant..** 
37a40 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
37a50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
37a60 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
37a70 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
37a80 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
37a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
37aa0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
37ab0 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
37ac0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
37ad0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
37ae0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
37af0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
37b00 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
37b10 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
37b20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37b30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
37b40 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
37b50 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
37b60 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
37b70 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
37b80 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  that running any
37b90 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65   other SQL state
37ba0 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  ments, including
37bb0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
37bc0 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79  ts,.** or merely
37bd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
37be0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
37bf0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
37c00 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79  p()] will modify
37c10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
37c30 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
37c40 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
37c50 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
37c60 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
37c70 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
37c80 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
37c90 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
37ca0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
37cb0 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
37cc0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
37cd0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
37ce0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
37cf0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
37d00 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
37d10 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
37d20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
37d30 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
37d40 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
37d50 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
37d60 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
37d70 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
37d80 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
37d90 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
37da0 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
37db0 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
37dc0 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
37dd0 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
37de0 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
37df0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
37e00 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
37e10 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
37e20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37e30 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
37e40 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
37e50 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
37e60 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
37e70 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
37e80 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
37e90 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
37ea0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
37eb0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
37ec0 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
37ed0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
37ee0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
37ef0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
37f00 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
37f10 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
37f20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
37f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37f40 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
37f50 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
37f60 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37f70 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
37f80 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
37f90 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
37fa0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
37fb0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
37fc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
37fd0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
37fe0 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
37ff0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
38000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38010 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
38020 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
38030 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
38040 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38050 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
38060 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
38070 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
38080 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
380a0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
380b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
380c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
380d0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
380e0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
380f0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
38100 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
38110 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
38120 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
38130 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
38140 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
38150 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
38160 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
38170 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
38180 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
38190 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
381a0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
381b0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
381c0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
381d0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
381e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
381f0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
38200 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
38210 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
38220 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
38230 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
38240 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
38250 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
38260 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
38270 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
38280 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
38290 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
382a0 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
382b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
382c0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
382d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
382e0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
382f0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
38300 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
38310 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
38320 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
38330 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
38340 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
38350 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
38360 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
38370 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
38380 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
38390 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
383a0 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
383b0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
383c0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
383d0 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
383e0 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
383f0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
38400 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
38410 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
38420 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
38430 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
38440 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
38450 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
38460 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
38470 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
38480 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
38490 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
384a0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
384b0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
384c0 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
384d0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
384e0 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
384f0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
38500 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
38510 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
38520 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
38530 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
38540 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
38550 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
38560 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
38570 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
38580 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
38590 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
385a0 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
385b0 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
385c0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
385d0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
385e0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
385f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
38600 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
38610 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
38620 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
38630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
38640 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
38650 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
38660 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
38670 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
38680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
38690 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
386a0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
386b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
386c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
386d0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
386e0 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
386f0 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
38700 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
38710 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
38720 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
38730 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
38740 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
38750 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
38760 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
38770 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
38780 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
38790 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
387a0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
387b0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
387c0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
387d0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
387e0 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
387f0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
38800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38810 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
38820 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
38830 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
38840 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
38850 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
38860 5d