/ Hex Artifact Content
Login

Artifact 19706a000717456c4963bb0f96262581436ffb5a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
86e0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
86f0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
8700: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8710: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8720: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8730: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8740: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8750: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8760: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8770: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8780: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8790: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
87a0: 20 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73   those to values
87b0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
87c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
87d0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
87e0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
87f0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8800: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8810: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8820: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8830: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
8840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8860: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
8870: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
8880: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
8890: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
88a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
88b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
88c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
88d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
88e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
88f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
8900: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8910: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
8920: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
8930: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
8940: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
8950: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
8960: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
8970: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
8980: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
8990: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
89a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
89b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
89c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
89d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
89e0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
89f0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
8a00: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
8a10: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
8a20: 69 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73  ite AHead Log] s
8a30: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
8a40: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
8a50: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
8a60: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
8a70: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
8a80: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
8a90: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
8aa0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
8ab0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
8ac0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
8ad0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
8ae0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
8af0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
8b00: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
8b10: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
8b20: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
8b30: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
8b40: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
8b50: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
8b60: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
8b70: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
8b80: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
8b90: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
8ba0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8bc0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
8bd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8be0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
8bf0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
8c00: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
8c10: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
8c20: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
8c30: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
8c40: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
8c50: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
8c60: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8c70: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
8c80: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
8c90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
8ca0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
8cb0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
8cc0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
8cd0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
8ce0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
8cf0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
8d00: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
8d10: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
8d20: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
8d30: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
8d40: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
8d50: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
8d60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
8d70: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
8d80: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
8d90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
8da0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
8db0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
8dc0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
8dd0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
8de0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
8df0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
8e00: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
8e10: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
8e20: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
8e30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
8e40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
8e50: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
8e60: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
8e70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8e80: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e90: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
8ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
8eb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8ec0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
8ed0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
8ee0: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
8ef0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
8f00: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
8f10: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
8f20: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f30: 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66  NT        5.#def
8f40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8f50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
8f60: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
8f70: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8f80: 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66  INTER     7.#def
8f90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8fa0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
8fb0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
8fc0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8fd0: 56 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66  V_RETRY   9.#def
8fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8ff0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
9000: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9020: 54 45 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a  TE       11../*.
9030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9040: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9050: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9060: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9070: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9080: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9090: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
90a0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
90b0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
90c0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
90d0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
90e0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
90f0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
9100: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
9110: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
9120: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
9130: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
9140: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
9150: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
9160: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
9170: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
9180: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
9190: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
91a0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
91b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
91c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
91d0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
91e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
91f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
9200: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
9210: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
9220: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
9230: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
9240: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
9250: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
9260: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
9270: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
9280: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
9290: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
92a0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
92b0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
92c0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
92d0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
92e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
92f0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
9300: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
9310: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
9320: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
9330: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
9340: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
9350: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
9360: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
9370: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
9380: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
9390: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
93a0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
93b0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
93c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
93d0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
93e0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
93f0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
9400: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
9410: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
9420: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
9430: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
9440: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
9450: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
9460: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
9470: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
9480: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
9490: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
94a0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
94b0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
94c0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
94d0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
94e0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
94f0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
9500: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
9510: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
9520: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
9530: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
9540: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
9550: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
9560: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
9570: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
9580: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
9590: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
95a0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
95b0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
95c0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
95d0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
95e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
95f0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
9600: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
9610: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
9620: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
9630: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
9640: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
9650: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
9660: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
9670: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
9680: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
9690: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
96a0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
96b0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
96c0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
96d0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
96e0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
96f0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
9700: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
9710: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
9720: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9730: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
9740: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
9750: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
9760: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
9770: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
9780: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
9790: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
97a0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
97b0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
97c0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
97d0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
97e0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
97f0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
9800: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
9810: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
9820: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
9830: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
9840: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
9850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
9860: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
9870: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
9880: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
9890: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
98a0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
98b0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
98c0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
98d0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
98e0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
98f0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
9900: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
9910: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
9920: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
9930: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c  re than.** 10 al
9940: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
9950: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
9960: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
9970: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
9980: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
9990: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
99a0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
99b0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
99c0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
99d0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
99e0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
99f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9a00: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
9a10: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
9a20: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
9a30: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
9a40: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
9a50: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
9a60: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
9a70: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
9a80: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
9a90: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
9aa0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
9ab0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
9ac0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
9ad0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
9ae0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
9af0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
9b00: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
9b10: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
9b20: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
9b30: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
9b40: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
9b50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9b60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
9b70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
9b80: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
9b90: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
9ba0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
9bb0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
9bc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
9bd0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
9be0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9bf0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
9c00: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
9c10: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
9c20: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
9c30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
9c40: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
9c50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
9c60: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
9c70: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
9c80: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
9c90: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
9ca0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
9cb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
9cc0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
9cd0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
9ce0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
9cf0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
9d00: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
9d10: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
9d20: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
9d30: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
9d40: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
9d50: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
9d60: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
9d70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9d80: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
9d90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9da0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
9db0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9dc0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
9dd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9de0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
9df0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
9e00: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
9e10: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
9e20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
9e30: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
9e40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
9e50: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
9e60: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9e70: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
9e80: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
9e90: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
9ea0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
9eb0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
9ec0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
9ed0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
9ee0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
9ef0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
9f00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9f10: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
9f20: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
9f30: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
9f40: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
9f50: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
9f60: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
9f70: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
9f80: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
9f90: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
9fa0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
9fb0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
9fc0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
9fd0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
9fe0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
9ff0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a000: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
a010: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
a020: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
a030: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
a040: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
a050: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
a060: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
a070: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
a080: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
a090: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
a0a0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
a0b0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
a0c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
a0d0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
a0e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a0f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a100: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
a110: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
a120: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
a130: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
a140: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
a150: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a160: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
a170: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
a180: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
a190: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
a1a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
a1b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a1c0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
a1d0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
a1e0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
a1f0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
a200: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
a210: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
a220: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
a230: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
a240: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
a250: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
a260: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
a270: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
a280: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
a290: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
a2a0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
a2b0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
a2c0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
a2d0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
a2e0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
a2f0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
a300: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
a310: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
a320: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
a330: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
a340: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
a350: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
a360: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
a370: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
a380: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
a390: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
a3a0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
a3b0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
a3c0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
a3d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
a3e0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
a3f0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
a400: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
a410: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
a420: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
a430: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
a440: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
a450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
a460: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
a470: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
a480: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
a490: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
a4a0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
a4b0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
a4c0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
a4d0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
a4e0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
a4f0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
a500: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
a510: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
a520: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
a530: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
a540: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
a550: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
a560: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
a570: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
a580: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
a590: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
a5a0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
a5b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
a5c0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
a5d0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
a5e0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
a5f0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
a600: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
a610: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
a620: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
a630: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
a640: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
a650: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
a660: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
a670: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
a680: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
a690: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
a6a0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
a6b0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
a6c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
a6d0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
a6e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
a6f0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
a700: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
a710: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a720: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
a730: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
a740: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
a750: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
a760: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
a770: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
a780: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
a790: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
a7a0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
a7b0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
a7c0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
a7d0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
a7e0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
a7f0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
a800: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
a810: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
a820: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
a830: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
a840: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
a850: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
a860: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
a870: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
a880: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
a890: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
a8a0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
a8b0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
a8c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
a8d0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
a8e0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
a8f0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
a900: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
a910: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
a920: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
a930: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
a940: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
a950: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
a960: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a970: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
a980: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
a990: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
a9a0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
a9b0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
a9c0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
a9d0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
a9e0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
a9f0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
aa00: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
aa10: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
aa20: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
aa30: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
aa40: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
aa50: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
aa60: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
aa70: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
aa80: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
aa90: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
aaa0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
aab0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
aac0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
aad0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
aae0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
aaf0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
ab00: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
ab10: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
ab20: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ab30: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ab40: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ab50: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ab60: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ab70: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ab80: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ab90: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
aba0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
abb0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
abc0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
abd0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
abe0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
abf0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
ac00: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
ac10: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
ac20: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
ac30: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
ac40: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ac50: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
ac60: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
ac70: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
ac80: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
ac90: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
aca0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
acb0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
acc0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
acd0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
ace0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
acf0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
ad00: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
ad10: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
ad20: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
ad30: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
ad40: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
ad50: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
ad60: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
ad70: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
ad80: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
ad90: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
ada0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
adb0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
adc0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
add0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
ade0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
adf0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
ae00: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
ae10: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
ae20: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
ae30: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
ae40: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
ae50: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
ae60: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
ae70: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
ae80: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
ae90: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
aea0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
aeb0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
aec0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
aed0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
aee0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
aef0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
af00: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
af10: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
af20: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
af30: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
af40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
af50: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
af60: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
af70: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
af80: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
af90: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
afa0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
afb0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
afc0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
afd0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
afe0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
aff0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
b000: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
b010: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
b020: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
b030: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
b040: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
b050: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
b060: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b070: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
b080: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
b090: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
b0a0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
b0b0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
b0c0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
b0d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
b0e0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
b0f0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
b100: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
b110: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
b120: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
b130: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
b140: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
b150: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
b160: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
b170: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
b180: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
b190: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
b1a0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
b1b0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
b1c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
b1d0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
b1e0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
b1f0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
b200: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
b210: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
b220: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
b230: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
b240: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
b250: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
b260: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b270: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
b280: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
b290: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
b2a0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
b2b0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
b2c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b2d0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
b2e0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
b2f0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
b300: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b310: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
b320: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
b330: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
b340: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
b350: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b360: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b370: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
b380: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
b390: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
b3a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b3b0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
b3c0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
b3d0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
b3e0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
b3f0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
b400: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
b410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
b420: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
b430: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
b440: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
b450: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
b460: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
b470: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
b480: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
b490: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
b4a0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
b4b0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
b4c0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
b4d0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
b4e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
b4f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
b500: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
b510: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
b520: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
b530: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
b540: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
b550: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
b560: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
b570: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
b580: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
b590: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
b5a0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
b5b0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
b5c0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
b5d0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
b5e0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
b5f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
b600: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
b610: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
b620: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
b630: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
b640: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
b650: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
b660: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
b670: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
b680: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
b690: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
b6a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b6b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
b6c0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
b6d0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
b6e0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
b6f0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
b700: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b710: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
b720: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
b730: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
b740: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b750: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
b760: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
b770: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b780: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
b790: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
b7a0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
b7b0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
b7c0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
b7d0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
b7e0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
b7f0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
b800: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
b810: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
b820: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
b830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b840: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
b850: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
b860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
b870: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
b880: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
b890: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
b8a0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
b8b0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
b8c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
b8d0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
b8e0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
b8f0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
b900: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
b910: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
b920: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
b930: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
b940: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
b950: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
b960: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
b970: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
b980: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
b990: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b9a0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
b9b0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
b9c0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
b9d0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
b9e0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
b9f0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
ba00: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
ba10: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
ba20: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
ba30: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
ba40: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
ba50: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
ba60: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ba70: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
ba80: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
ba90: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
baa0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
bab0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
bac0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
bad0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
bae0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
baf0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
bb00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
bb10: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
bb20: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
bb30: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
bb40: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
bb50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
bb60: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
bb70: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
bb80: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
bb90: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
bba0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
bbb0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
bbc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bbd0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
bbe0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
bbf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
bc00: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
bc10: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
bc20: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
bc30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bc40: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
bc50: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
bc60: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
bc70: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
bc80: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
bc90: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
bca0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
bcb0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
bcc0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
bcd0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
bce0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
bcf0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
bd00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bd10: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
bd20: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
bd30: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
bd40: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
bd50: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
bd60: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
bd70: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
bd80: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
bd90: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
bda0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
bdb0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
bdc0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
bdd0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
bde0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
bdf0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
be00: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
be10: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
be20: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
be30: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
be40: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
be50: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
be60: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
be70: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
be80: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
be90: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
bea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
beb0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
bec0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
bed0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
bee0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
bef0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
bf00: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
bf10: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
bf20: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
bf30: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
bf40: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
bf50: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
bf60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
bf70: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
bf80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
bf90: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
bfa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
bfb0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
bfc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
bfd0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
bfe0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bff0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
c000: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
c010: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
c020: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
c030: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
c040: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
c050: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
c060: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
c070: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
c080: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
c090: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
c0a0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
c0b0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
c0c0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
c0d0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
c0e0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
c0f0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
c100: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
c110: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
c120: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
c130: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
c140: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c150: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
c160: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
c170: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
c180: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
c190: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
c1a0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
c1b0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
c1c0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
c1d0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
c1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
c1f0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
c200: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
c210: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
c220: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
c230: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
c240: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
c250: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
c260: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
c270: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
c280: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
c290: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
c2a0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
c2b0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
c2c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
c2d0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
c2e0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
c2f0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
c300: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
c310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c320: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
c330: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
c340: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
c350: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
c360: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
c370: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c380: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
c390: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
c3a0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
c3b0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
c3c0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
c3d0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
c3e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
c3f0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
c400: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
c410: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
c420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
c430: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
c440: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c450: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
c460: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
c470: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
c480: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
c490: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
c4a0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
c4b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c4c0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
c4d0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
c4e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c4f0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
c500: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
c510: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
c520: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
c530: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
c540: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
c550: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
c560: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c570: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
c580: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
c590: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
c5a0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
c5b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
c5c0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
c5d0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
c5e0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
c5f0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
c600: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
c610: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
c620: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
c630: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
c640: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
c650: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
c660: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
c670: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
c680: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
c690: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
c6a0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
c6b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
c6c0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
c6d0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
c6e0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
c6f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
c700: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
c710: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
c720: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
c730: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c740: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
c750: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
c760: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
c770: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
c780: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c790: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
c7a0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
c7b0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
c7c0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
c7d0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
c7e0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
c7f0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
c800: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
c810: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
c820: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
c830: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
c840: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
c850: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
c860: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
c870: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
c880: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
c890: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
c8a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
c8b0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
c8c0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
c8d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c8e0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
c8f0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
c900: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
c910: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
c920: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c940: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
c950: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
c960: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
c970: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
c980: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
c990: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
c9a0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
c9b0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
c9c0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c9d0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
c9e0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
c9f0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
ca00: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
ca10: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
ca20: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
ca30: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
ca40: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
ca50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
ca60: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
ca70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
ca80: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
ca90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
caa0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
cab0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
cac0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
cad0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
cae0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
caf0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
cb00: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
cb10: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
cb20: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
cb30: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
cb40: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
cb50: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
cb60: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
cb70: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
cb80: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
cb90: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
cba0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
cbb0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
cbc0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
cbd0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
cbe0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
cbf0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
cc00: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
cc10: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
cc20: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
cc30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
cc40: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
cc50: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
cc60: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
cc70: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
cc80: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
cc90: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
cca0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
ccb0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
ccc0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
ccd0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
cce0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
ccf0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
cd00: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
cd10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
cd20: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
cd30: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
cd40: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
cd50: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
cd60: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
cd70: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
cd80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
cd90: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
cda0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
cdb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
cdc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
cdd0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
cde0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
cdf0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
ce00: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
ce10: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
ce20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
ce30: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
ce40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ce50: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
ce60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
ce70: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
ce80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ce90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
cea0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ceb0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
cec0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ced0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cee0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
cef0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
cf00: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
cf10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
cf20: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
cf30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
cf40: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
cf50: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
cf60: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
cf70: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
cf80: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
cf90: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
cfa0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
cfb0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
cfc0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
cfd0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
cfe0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
cff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
d000: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
d010: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
d020: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
d030: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
d040: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
d050: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
d060: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
d070: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
d080: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
d090: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
d0a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d0b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
d0c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
d0d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
d0e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
d0f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
d100: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
d110: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
d120: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
d130: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
d140: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
d150: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d160: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
d170: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
d180: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
d190: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
d1a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d1b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
d1c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
d1d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d1e0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
d1f0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
d200: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
d210: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
d220: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
d230: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
d240: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
d250: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
d260: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
d270: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
d280: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
d290: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
d2a0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
d2b0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
d2c0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
d2d0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
d2e0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
d2f0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
d300: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
d310: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
d320: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
d330: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d340: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
d350: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
d360: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
d370: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
d380: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
d390: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
d3a0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
d3b0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
d3c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
d3d0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
d3e0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
d3f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d400: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
d410: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
d420: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
d430: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
d440: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
d450: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
d460: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
d470: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d480: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
d490: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
d4a0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
d4b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d4c0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
d4d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
d4e0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
d4f0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
d500: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
d510: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
d520: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d530: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
d540: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
d550: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d560: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
d570: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
d580: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
d590: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
d5a0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
d5b0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
d5c0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
d5d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d5e0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
d5f0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
d600: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
d610: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
d620: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
d630: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
d640: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
d650: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
d660: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
d670: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d680: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
d690: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
d6a0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
d6b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d6c0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d6d0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
d6e0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
d6f0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
d700: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
d710: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
d720: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
d730: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
d740: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
d750: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
d760: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
d770: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d780: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
d790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
d7a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d7b0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
d7c0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
d7d0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
d7e0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
d7f0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
d800: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
d810: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
d820: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
d830: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
d840: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
d850: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
d860: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
d870: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d880: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
d890: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d8a0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
d8b0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d8c0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
d8d0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
d8e0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
d8f0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
d900: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
d910: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
d920: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
d930: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
d940: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
d950: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d960: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
d970: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
d980: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
d990: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
d9a0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
d9b0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
d9c0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
d9d0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d9e0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
d9f0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
da00: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
da10: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
da20: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
da30: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
da40: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
da50: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
da60: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
da70: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
da80: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
da90: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
daa0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
dab0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
dac0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
dad0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
dae0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
daf0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
db00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
db10: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
db20: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
db30: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
db40: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
db50: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
db60: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
db70: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
db80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
db90: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
dba0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
dbb0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
dbc0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
dbd0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dbe0: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
dbf0: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
dc00: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
dc10: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
dc20: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
dc30: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
dc40: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
dc50: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
dc60: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
dc70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
dc80: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
dc90: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
dca0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
dcb0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
dcc0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
dcd0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
dce0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
dcf0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
dd00: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
dd10: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
dd20: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
dd30: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
dd40: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
dd50: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
dd60: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
dd70: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
dd80: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
dd90: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
dda0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ddb0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ddc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ddd0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
dde0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ddf0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
de00: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
de10: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
de20: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
de30: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
de40: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
de50: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
de60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
de70: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
de80: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
de90: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
dea0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
deb0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
dec0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
ded0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
dee0: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
def0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
df00: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
df10: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
df20: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
df30: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
df40: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
df50: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
df60: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
df70: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
df90: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
dfa0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
dfb0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
dfc0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
dfd0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
dfe0: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
dff0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
e000: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
e010: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
e020: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e030: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
e040: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
e050: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
e060: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
e070: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
e080: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
e090: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
e0a0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
e0b0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
e0c0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
e0d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
e0e0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
e0f0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
e100: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
e110: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
e120: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
e130: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
e140: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
e150: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
e160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e170: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
e180: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
e190: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
e1a0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
e1b0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
e1c0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
e1d0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
e1e0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
e1f0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
e200: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
e210: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
e220: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
e230: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
e240: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
e250: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
e260: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
e270: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
e280: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e290: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e2a0: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
e2b0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
e2c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
e2d0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e2e0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
e2f0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
e300: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
e310: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
e320: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
e330: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
e340: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
e350: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
e360: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
e370: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
e380: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e390: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
e3a0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
e3b0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
e3c0: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
e3d0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
e3e0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
e3f0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
e400: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
e410: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
e420: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
e430: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
e440: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
e450: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
e460: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
e470: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
e480: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
e490: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
e4a0: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
e4b0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
e4c0: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e4e0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
e4f0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
e500: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
e510: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
e520: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
e530: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
e540: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
e550: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
e560: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
e570: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
e580: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
e590: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e5a0: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
e5b0: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
e5c0: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
e5d0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
e5e0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
e5f0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
e600: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
e610: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
e620: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
e630: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
e640: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
e650: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
e660: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
e670: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
e680: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
e690: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
e6a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
e6b0: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
e6c0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
e6d0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
e6e0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
e6f0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
e700: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
e710: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
e720: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
e730: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
e740: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
e750: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
e760: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
e770: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
e780: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
e790: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
e7a0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
e7b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
e7c0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
e7d0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
e7e0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
e7f0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
e800: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
e810: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
e820: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
e830: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
e840: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
e850: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
e860: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
e870: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
e880: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
e890: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
e8a0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
e8b0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
e8c0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
e8d0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
e8e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e8f0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
e900: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
e910: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
e920: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
e930: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
e940: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
e950: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
e960: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
e970: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
e980: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
e990: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
e9a0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
e9b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
e9c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e9d0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
e9e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
e9f0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
ea00: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
ea10: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
ea20: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
ea30: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
ea40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
ea50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
ea70: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
ea80: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
ea90: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
eaa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
eab0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
eac0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
ead0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
eae0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
eaf0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
eb00: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
eb10: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
eb20: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
eb30: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
eb40: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
eb50: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
eb60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
eb70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
eb80: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
eb90: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
eba0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
ebb0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
ebc0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
ebd0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
ebe0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
ebf0: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
ec00: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ec10: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
ec20: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ec30: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
ec40: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
ec50: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
ec60: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
ec70: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
ec80: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
ec90: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
eca0: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
ecb0: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
ecc0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
ecd0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
ece0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
ecf0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
ed00: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
ed10: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ed20: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
ed30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ed40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ed50: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ed60: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ed70: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ed80: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
ed90: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
eda0: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
edb0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
edc0: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
edd0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
ede0: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
edf0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ee00: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
ee10: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
ee20: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
ee30: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
ee40: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
ee50: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
ee60: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
ee70: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
ee80: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
ee90: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
eea0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
eeb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
eec0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
eed0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
eee0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
eef0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
ef00: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
ef10: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
ef20: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ef30: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
ef40: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
ef50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ef60: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
ef70: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
ef80: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
ef90: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
efa0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
efb0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
efc0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
efd0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
efe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
eff0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
f000: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
f010: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
f020: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
f030: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
f040: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
f050: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
f060: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
f070: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
f080: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
f090: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f0a0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
f0b0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
f0c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f0d0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
f0e0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
f0f0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
f100: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
f110: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
f120: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
f130: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
f140: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
f150: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
f160: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
f170: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
f180: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
f190: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
f1a0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
f1b0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
f1c0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
f1d0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
f1e0: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
f1f0: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
f200: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f210: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
f220: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
f230: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
f240: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
f250: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
f260: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
f270: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
f280: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
f290: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
f2a0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
f2b0: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
f2c0: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
f2d0: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
f2e0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
f2f0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
f300: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f310: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
f320: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
f330: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
f340: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
f350: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
f360: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
f370: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
f380: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
f390: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
f3a0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
f3b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f3c0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
f3d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
f3e0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
f3f0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
f400: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
f410: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
f420: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
f430: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
f440: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
f450: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
f460: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
f470: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
f480: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f490: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f4a0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f4b0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f4c0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f4d0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f4e0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
f4f0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
f500: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
f510: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
f520: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f530: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
f540: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
f550: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
f560: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
f570: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
f580: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f590: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
f5a0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f5b0: 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
f5c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f5d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f5e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f5f0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f600: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f610: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f620: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
f630: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
f640: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
f650: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
f660: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
f670: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
f680: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f690: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
f6a0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
f6b0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
f6c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
f6d0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
f6e0: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
f6f0: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
f700: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
f710: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
f720: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f730: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
f740: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
f750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
f760: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
f770: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
f780: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
f790: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
f7a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
f7b0: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
f7c0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
f7d0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
f7e0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
f7f0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
f800: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
f810: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
f820: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
f830: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
f840: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f850: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
f860: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
f870: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
f880: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
f890: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
f8a0: 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
f8b0: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
f8c0: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
f8d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f8e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
f8f0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
f900: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
f910: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
f920: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
f930: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
f940: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
f950: 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
f960: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
f970: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
f980: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f990: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
f9a0: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f9b0: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
f9c0: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
f9d0: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
f9e0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
f9f0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
fa00: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
fa10: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
fa20: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
fa30: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
fa40: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
fa50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
fa60: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
fa70: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
fa80: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
fa90: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
faa0: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
fab0: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
fac0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
fad0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
fae0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
faf0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
fb00: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
fb10: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
fb20: 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
fb30: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
fb40: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
fb50: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
fb60: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
fb70: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
fb80: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
fb90: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
fba0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
fbb0: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
fbc0: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
fbd0: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
fbe0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
fbf0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
fc00: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
fc10: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
fc20: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
fc30: 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
fc40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc50: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
fc60: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
fc70: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
fc80: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
fc90: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
fca0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
fcb0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
fcc0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
fcd0: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
fce0: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
fcf0: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
fd00: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
fd10: 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
fd20: 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
fd30: 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
fd40: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
fd50: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
fd60: 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
fd70: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
fd80: 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
fd90: 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
fda0: 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
fdb0: 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
fdc0: 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
fdd0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fde0: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
fdf0: 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
fe00: 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
fe10: 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
fe20: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
fe30: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
fe40: 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
fe50: 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
fe60: 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
fe70: 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
fe80: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
fe90: 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
fea0: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
feb0: 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
fec0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
fed0: 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
fee0: 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
fef0: 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
ff00: 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
ff10: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
ff20: 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
ff30: 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
ff40: 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
ff50: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
ff60: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
ff70: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
ff80: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
ff90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ffa0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
ffb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
ffc0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
ffd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
ffe0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
fff0: 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10000 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10010 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10020 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10030 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10040 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10050 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10060 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10070 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10080 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10090 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
100a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
100b0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
100c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
100d0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
100e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
100f0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
10100 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
10110 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
10120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
10130 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
10140 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
10150 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
10160 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
10170 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
10180 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
10190 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
101a0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
101b0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
101c0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
101d0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
101e0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
101f0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
10200 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
10210 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
10220 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
10230 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
10240 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
10250 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
10260 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
10270 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
10280 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
10290 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
102a0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
102b0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
102c0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
102d0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
102e0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
102f0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
10300 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
10310 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
10320 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
10330 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
10340 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
10350 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
10360 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
10370 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
10380 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
10390 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
103a0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
103b0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
103c0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
103d0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
103e0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
103f0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
10400 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
10410 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
10420 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
10430 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
10440 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
10450 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
10460 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10470 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
10480 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
10490 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
104a0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
104b0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
104c0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
104d0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
104e0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
104f0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
10500 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
10510 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
10520 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10530 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
10540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
10550 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
10560 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
10570 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
10580 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
10590 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
105a0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
105b0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
105c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
105d0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
105e0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
105f0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
10600 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
10610 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10620 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
10630 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
10640 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
10650 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
10660 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
10670 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
10680 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
10690 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
106a0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
106b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
106c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
106d0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
106e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
106f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
10700 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
10710 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
10720 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10730 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
10740 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
10750 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
10760 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
10770 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
10780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10790 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
107a0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
107b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
107c0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
107d0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
107e0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
107f0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
10800 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
10810 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
10820 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
10830 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
10840 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
10850 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
10860 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
10870 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
10880 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
10890 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
108a0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
108b0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
108c0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
108d0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
108e0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
108f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
10900 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
10910 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
10920 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
10930 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
10940 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
10950 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
10960 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
10970 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
10980 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10990 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
109a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
109b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
109c0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
109d0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
109e0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
109f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10a00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10a10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10a20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10a30 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
10a40 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
10a50 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
10a60 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
10a70 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
10a80 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
10a90 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
10aa0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
10ab0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
10ac0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
10ad0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
10ae0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
10af0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10b00 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
10b10 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
10b20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
10b30 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
10b40 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10b50 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10b60 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10b70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10b80 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10b90 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
10ba0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
10bb0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
10bc0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
10bd0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
10be0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
10bf0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10c00 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
10c10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
10c20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10c30 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
10c40 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
10c50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10c70 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
10c80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10c90 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
10ca0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
10cb0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
10cc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10cd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10ce0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10cf0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10d00 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10d10 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
10d20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10d30 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10d40 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10d50 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
10d60 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
10d70 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
10d80 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
10d90 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
10da0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
10db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
10dc0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
10dd0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
10de0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
10df0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
10e00 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
10e10 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
10e20 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
10e30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10e40 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10e50 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10e60 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10e70 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10e80 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10e90 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
10ea0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10eb0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10ec0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10ed0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10ee0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ef0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
10f00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10f10 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
10f20 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
10f30 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10f40 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10f50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10f60 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
10f70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10f80 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
10f90 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10fa0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
10fb0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
10fc0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
10fd0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
10fe0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
10ff0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11000 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
11010 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
11020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11040 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11050 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11060 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
11070 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
11080 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11090 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
110a0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
110b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
110c0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
110d0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
110e0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
110f0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
11100 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11110 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
11120 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
11130 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
11140 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
11150 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
11160 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11170 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
11180 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
11190 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
111a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
111b0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
111c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
111d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
111e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
111f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11200 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11210 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
11220 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
11230 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
11240 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
11250 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
11260 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
11270 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
11280 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
11290 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
112a0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
112b0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
112c0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
112d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
112e0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
112f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11300 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
11310 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11320 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
11330 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11340 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11350 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11360 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11370 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
11380 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11390 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
113a0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
113b0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
113c0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
113d0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
113e0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
113f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11400 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
11410 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
11420 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
11430 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
11440 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
11450 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
11460 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
11470 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
11480 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
11490 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
114a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
114b0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
114c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
114d0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
114e0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
114f0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
11500 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
11510 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
11520 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
11530 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
11540 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
11550 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
11560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
11570 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
11580 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
11590 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
115a0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
115b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
115c0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
115d0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
115e0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
115f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11600 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
11610 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
11620 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
11630 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
11640 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
11650 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
11660 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11670 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
11680 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
11690 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
116a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
116b0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
116c0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
116d0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
116e0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
116f0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
11700 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
11710 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
11720 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
11730 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
11740 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
11750 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
11760 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
11770 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
11780 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
11790 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
117a0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
117b0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
117c0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
117d0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
117e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
117f0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
11800 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
11810 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
11820 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
11830 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
11840 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
11850 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
11860 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
11870 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11880 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
11890 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
118a0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
118b0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
118c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
118d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
118e0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
118f0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
11900 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
11910 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
11920 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
11930 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
11940 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
11950 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
11960 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
11970 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
11980 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
11990 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
119a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
119b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
119c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
119d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
119e0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
119f0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
11a00 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
11a10 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
11a20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
11a30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
11a40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
11a50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
11a60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
11a70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
11a80 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
11a90 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
11aa0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
11ab0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
11ac0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
11ad0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
11ae0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
11af0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
11b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11b10 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
11b20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
11b30 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
11b40 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
11b50 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
11b60 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
11b70 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
11b80 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
11b90 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
11ba0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
11bb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11bc0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
11bd0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
11be0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
11bf0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
11c00 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
11c10 4e 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  NIG_GETPCACHE.**
11c20 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
11c30 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
11c40 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
11c50 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
11c60 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
11c70 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
11c80 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
11c90 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
11ca0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
11cb0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
11cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11cd0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
11ce0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
11cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11d00 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
11d10 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
11d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11d30 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
11d40 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
11d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11d60 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
11d70 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
11d80 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11d90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11da0 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
11db0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
11dc0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
11dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11de0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
11df0 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
11e00 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
11e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11e20 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
11e30 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
11e40 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
11e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11e60 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
11e70 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
11e80 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
11e90 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
11ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11eb0 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
11ec0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
11ed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11ee0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
11ef0 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
11f00 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
11f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11f20 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
11f30 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
11f40 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11f50 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
11f60 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
11f70 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
11f80 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
11f90 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
11fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11fb0 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
11fc0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
11fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11fe0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
11ff0 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
12000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12010 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
12020 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
12030 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12040 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
12050 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
12060 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
12070 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12080 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
12090 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
120a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
120b0 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
120c0 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
120d0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
120e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
120f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
12100 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
12110 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12120 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  hods2* */../*.**
12130 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
12140 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
12150 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
12160 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
12170 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12180 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12190 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
121a0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
121b0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
121c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
121d0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
121e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
121f0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
12200 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
12210 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12220 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
12230 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
12240 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
12250 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
12260 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12270 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12280 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12290 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
122a0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
122b0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
122c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
122d0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
122e0 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
122f0 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
12300 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
12310 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
12320 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
12330 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
12340 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
12350 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
12360 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12370 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
12380 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
12390 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
123a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
123b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
123c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
123d0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
123e0 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
123f0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
12400 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
12410 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
12420 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
12430 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
12440 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
12450 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
12460 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
12470 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
12480 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12490 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
124a0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
124b0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
124c0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
124d0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
124e0 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
124f0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
12500 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
12510 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
12520 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
12530 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
12540 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
12550 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
12560 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
12570 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
12580 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12590 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
125a0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
125b0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
125c0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
125d0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
125e0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
125f0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
12600 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
12610 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12620 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
12630 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
12640 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
12650 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
12660 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
12670 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
12680 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
12690 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
126a0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
126b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
126c0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
126d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
126e0 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
126f0 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
12700 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
12710 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
12720 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
12730 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
12740 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
12750 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
12760 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
12770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12780 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
12790 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
127a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
127b0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
127c0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
127d0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
127e0 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
127f0 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
12800 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
12810 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
12820 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
12830 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12840 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
12850 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
12860 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
12870 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
12880 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
12890 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
128a0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
128b0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
128c0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
128d0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
128e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
128f0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
12900 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
12910 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
12920 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12930 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
12940 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
12950 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
12960 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
12970 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
12980 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
12990 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
129a0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
129b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
129c0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
129d0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
129e0 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
129f0 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
12a00 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
12a10 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
12a20 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
12a30 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
12a40 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
12a50 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
12a60 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
12a70 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
12a80 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
12a90 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
12aa0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
12ab0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
12ac0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
12ad0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
12ae0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
12af0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12b00 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
12b10 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
12b20 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
12b30 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
12b40 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
12b50 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
12b60 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
12b70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
12b80 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
12b90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12ba0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
12bb0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
12bc0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
12bd0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
12be0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
12bf0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
12c00 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
12c10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12c20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
12c30 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
12c40 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
12c50 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
12c60 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
12c70 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
12c80 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
12c90 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
12ca0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12cb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12cc0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
12cd0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
12ce0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
12cf0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
12d00 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
12d10 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
12d20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
12d30 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
12d40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
12d50 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
12d60 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
12d70 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
12d80 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
12d90 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
12da0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
12db0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12dc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12dd0 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
12de0 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
12df0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
12e00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12e10 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
12e20 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
12e30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12e40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
12e50 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
12e60 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
12e70 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
12e80 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
12e90 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
12ea0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
12eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
12ec0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
12ed0 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
12ee0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12ef0 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
12f00 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
12f10 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
12f20 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
12f30 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
12f40 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
12f50 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
12f60 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
12f70 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
12f80 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
12f90 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
12fa0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
12fb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12fc0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
12fd0 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
12fe0 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
12ff0 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
13000 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
13010 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
13020 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
13030 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
13040 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
13050 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
13060 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
13070 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
13080 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
13090 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
130a0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
130b0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
130c0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
130d0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
130e0 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
130f0 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
13100 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
13110 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
13120 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
13130 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
13140 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
13150 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
13160 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
13170 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
13180 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
13190 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
131a0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
131b0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
131c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
131d0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
131e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
131f0 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
13200 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
13210 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
13220 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
13230 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
13240 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
13250 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
13260 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
13270 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
13280 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
13290 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
132a0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
132b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
132c0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
132d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
132e0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
132f0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
13300 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
13310 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
13320 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
13330 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
13340 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
13350 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
13360 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
13370 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
13380 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
13390 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
133a0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
133b0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
133c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
133d0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
133e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
133f0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
13400 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
13410 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
13420 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
13430 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
13440 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
13450 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
13460 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
13470 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
13480 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
13490 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
134a0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
134b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
134c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
134d0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
134e0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
134f0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
13500 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
13510 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
13520 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
13530 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
13540 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
13550 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
13560 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
13570 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
13580 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
13590 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
135a0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
135b0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
135c0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
135d0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
135e0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
135f0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
13600 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
13610 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
13620 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
13630 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
13640 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
13650 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
13660 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
13670 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
13680 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
13690 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
136a0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
136b0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
136c0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
136d0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
136e0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
136f0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
13700 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
13710 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
13720 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
13730 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
13740 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
13750 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
13760 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
13770 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
13780 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
13790 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
137a0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
137b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
137c0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
137d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
137e0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
137f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
13800 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
13810 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
13820 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
13830 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
13840 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
13850 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
13860 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
13870 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
13880 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
13890 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
138a0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
138b0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
138c0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
138d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
138e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
138f0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
13900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13910 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
13920 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
13930 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
13940 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
13950 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
13960 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
13970 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
13980 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
13990 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
139a0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
139b0 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
139c0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
139d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
139e0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
139f0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13a00 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
13a10 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
13a20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
13a30 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
13a40 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
13a50 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
13a60 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
13a70 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
13a80 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
13a90 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
13aa0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
13ab0 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
13ac0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
13ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
13ae0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
13af0 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
13b00 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
13b10 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
13b20 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
13b30 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
13b40 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
13b50 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
13b60 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
13b70 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
13b80 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
13b90 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
13ba0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
13bb0 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
13bc0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
13bd0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
13be0 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
13bf0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
13c00 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
13c10 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
13c20 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
13c30 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
13c40 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
13c50 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
13c60 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
13c70 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
13c80 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
13c90 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
13ca0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
13cb0 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
13cc0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
13cd0 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
13ce0 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
13cf0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
13d00 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
13d10 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
13d20 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
13d30 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
13d40 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
13d50 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
13d60 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
13d70 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
13d80 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
13d90 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
13da0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
13db0 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
13dc0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
13dd0 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
13de0 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
13df0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
13e00 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
13e10 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
13e20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
13e30 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
13e40 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
13e50 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
13e60 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
13e70 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
13e80 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
13e90 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
13ea0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
13eb0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
13ec0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
13ed0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
13ee0 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
13ef0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
13f00 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13f10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
13f20 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
13f30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
13f40 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
13f50 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
13f60 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
13f70 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
13f80 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
13f90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
13fa0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
13fb0 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
13fc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
13fd0 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
13fe0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
13ff0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
14000 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
14010 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
14020 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
14030 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
14040 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
14050 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
14060 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
14070 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
14080 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
14090 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
140a0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
140b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
140c0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
140d0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
140e0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
140f0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
14100 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
14110 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14120 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
14130 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
14140 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
14150 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
14160 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
14170 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
14180 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
14190 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
141a0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
141b0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
141c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
141d0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
141e0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
141f0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
14200 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
14210 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
14220 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
14230 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
14240 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
14250 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
14260 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
14270 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
14280 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
14290 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
142a0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
142b0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
142c0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
142d0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
142e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
142f0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
14300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14310 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
14320 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
14330 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14340 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14350 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
14360 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
14370 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
14380 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
14390 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
143a0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
143b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
143c0 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
143d0 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
143e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
143f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
14400 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
14410 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
14420 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
14430 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
14440 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
14450 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
14460 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
14470 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
14480 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
14490 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
144a0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
144b0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
144c0 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
144d0 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
144e0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
144f0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
14500 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
14510 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
14520 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
14530 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
14540 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
14550 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
14560 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
14570 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
14580 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
14590 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
145a0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
145b0 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
145c0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
145d0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
145e0 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
145f0 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
14600 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
14610 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
14620 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
14630 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
14640 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
14650 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
14660 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
14670 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
14680 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
14690 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
146a0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
146b0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
146c0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
146d0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
146e0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
146f0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
14700 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
14710 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
14720 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
14730 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14740 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
14750 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
14760 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
14770 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
14780 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
14790 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
147a0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
147b0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
147c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
147d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
147e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
147f0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
14800 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
14810 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
14820 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
14830 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
14840 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
14850 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
14860 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
14870 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
14880 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
14890 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
148a0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
148b0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
148c0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
148d0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
148e0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
148f0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
14900 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
14910 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
14920 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
14930 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
14940 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
14950 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
14960 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
14970 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
14980 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
14990 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
149a0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
149b0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
149c0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
149d0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
149e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
149f0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
14a00 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
14a10 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
14a20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14a30 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
14a40 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
14a50 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
14a60 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
14a70 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
14a80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14a90 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
14aa0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
14ab0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
14ac0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
14ad0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
14ae0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
14af0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
14b00 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
14b10 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
14b20 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
14b30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
14b40 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
14b50 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
14b60 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
14b70 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
14b80 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
14b90 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
14ba0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
14bb0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
14bc0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
14bd0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
14be0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
14bf0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
14c00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
14c10 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
14c20 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
14c30 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
14c40 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
14c50 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
14c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14c70 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
14c80 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
14c90 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
14ca0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
14cb0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
14cc0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
14cd0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
14ce0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
14cf0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
14d00 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
14d10 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
14d20 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
14d30 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
14d40 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14d50 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
14d60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
14d70 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
14d80 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
14d90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
14da0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
14db0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
14dc0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
14dd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
14de0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
14df0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14e00 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
14e10 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
14e20 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
14e30 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
14e40 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
14e50 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
14e60 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
14e70 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
14e80 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
14e90 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
14ea0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
14eb0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
14ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
14ed0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
14ee0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
14ef0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14f00 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
14f10 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
14f20 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
14f30 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
14f40 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
14f50 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
14f60 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
14f70 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
14f80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
14f90 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
14fa0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
14fb0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
14fc0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
14fd0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
14fe0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
14ff0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
15000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
15010 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
15020 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
15030 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
15040 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
15050 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
15060 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
15070 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
15080 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
15090 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
150a0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
150b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
150c0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
150d0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
150e0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
150f0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
15100 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
15110 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
15120 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
15130 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
15140 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
15150 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
15160 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
15170 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
15180 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
15190 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
151a0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
151b0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
151c0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
151d0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
151e0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
151f0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
15200 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
15210 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
15220 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
15230 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
15240 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
15250 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
15260 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
15270 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
15280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
15290 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
152a0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
152b0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
152c0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
152d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
152e0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
152f0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
15300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
15310 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
15320 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
15330 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
15340 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
15350 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
15360 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
15370 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
15380 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
15390 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
153a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
153b0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
153c0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
153d0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
153e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
153f0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
15400 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
15410 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
15420 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
15430 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
15440 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
15450 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
15460 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
15470 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15480 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
15490 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
154a0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
154b0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
154c0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
154d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
154e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
154f0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
15500 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
15510 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
15520 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
15530 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
15540 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
15550 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
15560 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
15570 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
15580 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
15590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
155a0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
155b0 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
155c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
155d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
155e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
155f0 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
15600 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
15610 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
15620 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
15630 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
15640 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
15650 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
15660 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
15670 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
15680 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
15690 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
156a0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
156b0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
156c0 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
156d0 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
156e0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
156f0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
15700 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
15710 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
15720 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
15730 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
15740 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
15750 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
15760 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
15770 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
15780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
15790 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
157a0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
157b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
157c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
157d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
157e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
157f0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
15800 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
15810 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
15820 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
15830 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
15840 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15850 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
15860 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
15870 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
15880 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
15890 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
158a0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
158b0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
158c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
158d0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
158e0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
158f0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
15900 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
15910 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
15920 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
15930 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
15940 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
15950 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
15960 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
15970 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15980 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
15990 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
159a0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
159b0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
159c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
159d0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
159e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
159f0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
15a00 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
15a10 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
15a20 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
15a30 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
15a40 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
15a50 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
15a60 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
15a70 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
15a80 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
15a90 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
15aa0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
15ab0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
15ac0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
15ad0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
15ae0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15af0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
15b00 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
15b10 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
15b20 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
15b30 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
15b40 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
15b50 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
15b60 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
15b70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
15b80 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
15b90 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
15ba0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
15bb0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
15bc0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
15bd0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
15be0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
15bf0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
15c00 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
15c10 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
15c20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
15c30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15c40 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
15c50 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
15c60 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
15c70 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
15c80 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
15c90 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
15ca0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
15cb0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
15cc0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
15cd0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
15ce0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
15cf0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
15d00 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
15d10 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
15d20 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
15d30 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
15d40 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
15d50 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
15d60 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
15d70 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
15d80 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
15d90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
15da0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
15db0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
15dc0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
15dd0 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
15de0 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
15df0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15e00 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
15e10 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
15e20 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
15e30 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
15e40 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
15e50 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
15e60 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
15e70 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
15e80 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
15e90 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
15ea0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
15eb0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
15ec0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
15ed0 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
15ee0 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
15ef0 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
15f00 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
15f10 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
15f20 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
15f30 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
15f40 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
15f50 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
15f60 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
15f70 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
15f80 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
15f90 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
15fa0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
15fb0 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
15fc0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
15fd0 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
15fe0 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
15ff0 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
16000 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
16010 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
16020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
16030 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
16040 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
16050 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
16060 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
16070 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
16080 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
16090 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
160a0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
160b0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
160c0 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
160d0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
160e0 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
160f0 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
16100 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
16110 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
16120 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
16130 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
16140 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
16150 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
16160 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
16170 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
16180 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
16190 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
161a0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
161b0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
161c0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
161d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
161e0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
161f0 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
16200 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
16210 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
16220 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
16230 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
16240 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
16250 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
16260 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16270 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
16280 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
16290 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
162a0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
162b0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
162c0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
162d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
162e0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
162f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16300 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
16310 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
16320 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
16330 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
16340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
16350 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
16360 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
16370 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
16380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16390 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
163a0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
163b0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
163c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
163d0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
163e0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
163f0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
16400 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
16410 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
16420 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
16430 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
16440 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
16450 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
16460 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
16470 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
16480 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
16490 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
164a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
164b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
164c0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
164d0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
164e0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
164f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
16500 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
16510 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
16520 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16530 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
16540 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
16550 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
16560 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
16570 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
16580 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
16590 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
165a0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
165b0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
165c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
165d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
165e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
165f0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
16600 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
16610 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
16620 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
16630 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
16640 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
16650 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
16660 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
16670 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
16680 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
16690 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
166a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
166b0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
166c0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
166d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
166e0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
166f0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
16700 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
16710 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
16720 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
16730 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
16740 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
16750 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
16760 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16770 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
16780 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
16790 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
167a0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
167b0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
167c0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
167d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
167e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
167f0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
16800 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
16810 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
16820 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
16830 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
16840 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
16850 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
16860 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
16870 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
16880 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
16890 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
168a0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
168b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
168c0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
168d0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
168e0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
168f0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
16900 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
16910 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
16920 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
16930 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
16940 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
16950 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
16960 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
16970 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
16980 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
16990 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
169a0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
169b0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
169c0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
169d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
169e0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
169f0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
16a00 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
16a10 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
16a20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
16a30 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
16a40 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
16a50 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
16a60 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
16a70 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
16a80 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
16a90 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
16aa0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
16ab0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
16ac0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
16ae0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
16af0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
16b00 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
16b10 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
16b20 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
16b30 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
16b40 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
16b50 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
16b60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
16b70 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
16b80 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
16b90 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
16ba0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
16bb0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
16bc0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
16bd0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16be0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
16bf0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
16c00 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
16c10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16c20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
16c30 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
16c40 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
16c50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16c60 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
16c70 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
16c80 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
16c90 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
16ca0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
16cb0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
16cc0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16cd0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
16ce0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
16cf0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
16d00 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
16d10 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
16d20 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
16d30 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
16d40 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
16d50 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
16d60 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
16d70 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
16d80 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
16d90 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
16da0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
16db0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16dc0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
16dd0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16de0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
16df0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
16e00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
16e10 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
16e20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16e30 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
16e40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16e50 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
16e60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16e70 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
16e80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16e90 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
16ea0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
16eb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
16ec0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
16ed0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
16ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
16ef0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16f00 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
16f10 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
16f20 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
16f30 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
16f40 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
16f50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16f60 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
16f70 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
16f80 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
16f90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
16fa0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
16fb0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
16fc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
16fd0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
16fe0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
16ff0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
17000 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
17010 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
17020 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
17030 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
17040 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
17050 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
17060 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
17070 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
17080 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
17090 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
170a0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
170b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
170c0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
170d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
170e0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
170f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
17100 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
17110 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
17120 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
17130 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
17140 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
17150 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
17160 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
17170 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
17180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17190 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
171a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
171b0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
171c0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
171d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
171e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
171f0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
17200 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
17210 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
17220 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
17230 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
17240 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
17250 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
17260 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
17270 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
17280 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
17290 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
172a0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
172b0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
172c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
172d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
172e0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
172f0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
17300 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
17310 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
17320 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
17330 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
17340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
17350 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
17360 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
17370 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
17380 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
17390 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
173a0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
173b0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
173c0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
173d0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
173e0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
173f0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
17400 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
17410 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
17420 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
17430 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
17440 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
17450 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
17460 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
17470 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
17480 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
17490 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
174a0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
174b0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
174c0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
174d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
174e0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
174f0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
17500 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17510 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
17520 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
17530 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
17540 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
17550 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
17560 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
17570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17580 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
17590 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
175a0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
175b0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
175c0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
175d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
175e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
175f0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
17600 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
17610 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
17620 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
17630 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
17640 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
17650 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
17660 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
17670 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
17680 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
17690 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
176a0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
176b0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
176c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
176d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
176e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
176f0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
17700 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
17710 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
17720 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
17730 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
17740 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
17750 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
17760 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
17770 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
17780 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
17790 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
177a0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
177b0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
177c0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
177d0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
177e0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
177f0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
17800 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
17810 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
17820 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
17830 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
17840 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
17850 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
17860 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
17870 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
17880 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
17890 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
178a0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
178b0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
178c0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
178d0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
178e0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
178f0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
17900 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
17910 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
17920 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
17930 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
17940 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
17950 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
17960 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
17970 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
17980 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17990 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
179a0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
179b0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
179c0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
179d0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
179e0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
179f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
17a00 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
17a10 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
17a20 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
17a30 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
17a40 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
17a50 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
17a60 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
17a70 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
17a80 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
17a90 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
17aa0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
17ab0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
17ac0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
17ad0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
17ae0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
17af0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
17b00 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
17b10 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
17b20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
17b30 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
17b40 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
17b50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
17b60 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
17b70 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
17b80 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
17b90 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
17ba0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
17bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
17bc0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
17bd0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
17be0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
17bf0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
17c00 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
17c10 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
17c20 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
17c30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
17c40 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
17c50 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
17c60 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
17c70 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
17c80 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
17c90 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
17ca0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
17cb0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
17cc0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
17cd0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
17ce0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
17cf0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
17d00 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
17d10 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
17d20 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
17d30 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
17d40 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
17d50 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
17d60 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
17d70 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
17d80 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
17d90 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
17da0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
17db0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
17dc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17dd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17de0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
17df0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
17e00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17e10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
17e20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
17e30 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
17e40 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
17e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
17e70 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
17e80 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
17e90 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
17ea0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
17eb0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
17ec0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
17ed0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17ee0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
17ef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17f00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
17f10 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
17f20 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
17f30 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
17f40 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
17f50 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
17f60 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
17f70 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
17f80 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
17f90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17fa0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17fb0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
17fc0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
17fd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17fe0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
17ff0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
18000 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
18010 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
18020 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
18030 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
18040 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
18050 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
18060 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
18070 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
18080 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
18090 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
180a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
180b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
180c0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
180d0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
180e0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
180f0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
18100 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
18110 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
18120 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
18130 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
18140 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
18150 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
18160 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
18170 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
18180 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
18190 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
181a0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
181b0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
181c0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
181d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
181e0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
181f0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
18200 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
18210 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
18220 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
18230 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
18240 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
18250 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
18260 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
18270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18280 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
18290 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
182a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
182b0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
182c0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
182d0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
182e0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
182f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
18300 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
18310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18320 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
18330 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
18340 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
18350 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
18360 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
18370 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
18380 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
18390 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
183a0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
183b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
183c0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
183d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
183e0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
183f0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
18400 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
18410 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
18420 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
18430 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
18440 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
18450 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
18460 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
18470 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
18480 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
18490 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
184a0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
184b0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
184c0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
184d0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
184e0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
184f0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18500 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
18510 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
18520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18530 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
18540 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
18550 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
18560 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
18570 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
18580 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
18590 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
185a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
185b0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
185c0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
185d0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
185e0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
185f0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
18600 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
18610 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
18620 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
18630 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
18640 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
18650 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
18660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
18680 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
18690 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
186a0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
186b0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
186c0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
186d0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
186e0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
186f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
18700 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
18710 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
18720 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
18730 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
18740 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
18750 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
18760 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
18770 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
18780 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
18790 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
187a0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
187b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
187c0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
187d0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
187e0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
187f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
18800 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
18810 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
18820 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
18830 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
18840 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
18850 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
18860 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
18870 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
18880 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
18890 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
188a0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
188b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
188c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
188d0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
188e0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
188f0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
18900 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
18910 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
18920 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
18930 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
18940 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
18950 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
18960 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
18970 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
18980 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
18990 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
189a0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
189b0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
189c0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
189d0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
189e0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
189f0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
18a00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
18a10 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
18a20 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
18a30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
18a40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18a50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
18a60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
18a70 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
18a80 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
18a90 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
18aa0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
18ab0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
18ac0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
18ad0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18ae0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
18af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
18b00 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
18b10 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18b20 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
18b30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18b40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18b50 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
18b60 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
18b70 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
18b80 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
18b90 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
18ba0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
18bb0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
18bc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18bd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18be0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
18bf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
18c00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18c10 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
18c20 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
18c30 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
18c40 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
18c50 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
18c60 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
18c70 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
18c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
18c90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
18ca0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
18cb0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
18cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
18cd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
18ce0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
18cf0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
18d00 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
18d10 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
18d20 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
18d30 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
18d40 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18d50 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
18d60 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
18d70 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18d80 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
18d90 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
18da0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
18db0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
18dc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18dd0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
18de0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
18df0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
18e00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
18e10 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
18e20 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18e30 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
18e40 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
18e50 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
18e60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
18e70 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
18e80 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
18e90 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
18ea0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
18eb0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
18ec0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
18ed0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
18ee0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
18ef0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
18f00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
18f10 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
18f20 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
18f30 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
18f40 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
18f50 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
18f60 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
18f70 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
18f80 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
18f90 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
18fa0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
18fb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
18fc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
18fd0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
18fe0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
18ff0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
19000 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
19010 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
19020 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
19030 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
19040 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
19050 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
19060 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
19070 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
19080 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
19090 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
190a0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
190b0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
190c0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
190d0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
190e0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
190f0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
19100 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
19110 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
19120 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
19130 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
19140 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
19150 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
19160 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
19170 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
19180 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
19190 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
191a0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
191b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
191c0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
191d0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
191e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
191f0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
19200 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
19210 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
19220 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
19230 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
19240 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
19250 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
19260 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
19270 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
19280 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
19290 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
192a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
192b0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
192c0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
192d0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
192e0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
192f0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
19300 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
19310 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
19320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19330 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
19340 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
19350 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
19360 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
19370 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
19380 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
19390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
193a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
193b0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
193c0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
193d0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
193e0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
193f0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
19400 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
19410 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
19420 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19430 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
19440 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
19450 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
19460 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
19470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19480 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
19490 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
194a0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
194b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
194c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
194d0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
194e0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
194f0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
19500 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
19510 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
19520 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
19530 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
19540 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
19550 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
19560 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19570 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
19580 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
19590 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
195a0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
195b0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
195c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
195d0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
195e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
195f0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
19600 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
19610 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
19620 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
19630 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
19640 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
19650 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
19660 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
19670 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
19680 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
19690 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
196a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
196b0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
196c0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
196d0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
196e0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
196f0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
19700 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19710 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
19720 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
19730 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
19740 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
19750 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
19760 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
19770 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
19780 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
19790 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
197a0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
197b0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
197c0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
197d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
197e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
197f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
19800 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
19810 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
19820 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
19830 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
19840 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
19850 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
19860 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
19870 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
19880 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
19890 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
198a0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
198b0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
198c0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
198d0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
198e0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
198f0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
19900 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
19910 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
19920 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
19930 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
19940 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
19950 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
19960 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
19970 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
19980 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
19990 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
199a0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
199b0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
199c0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
199d0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
199e0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
199f0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
19a00 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
19a10 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
19a20 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
19a30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
19a40 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
19a50 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
19a60 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
19a70 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
19a80 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
19a90 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
19aa0 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
19ab0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
19ac0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
19ad0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
19ae0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
19af0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
19b00 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
19b10 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
19b20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
19b30 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
19b40 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
19b50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
19b60 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
19b70 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
19b80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
19b90 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
19ba0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
19bb0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
19bc0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
19bd0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
19be0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
19bf0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
19c00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19c10 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
19c20 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
19c40 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
19c50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
19c60 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
19c70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19c80 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
19c90 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
19ca0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
19cb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19cc0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
19cd0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
19ce0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
19cf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19d00 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
19d10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19d20 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
19d30 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
19d40 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
19d50 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
19d60 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
19d70 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
19d80 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
19d90 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
19da0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19db0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
19dc0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
19dd0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
19de0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
19df0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
19e00 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19e10 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
19e20 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
19e30 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
19e40 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
19e50 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
19e60 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
19e70 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
19e80 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
19e90 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
19ea0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
19eb0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
19ec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
19ed0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
19ee0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
19ef0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
19f00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19f10 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
19f20 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
19f30 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
19f40 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
19f50 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
19f60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
19f70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
19f80 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
19f90 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
19fa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19fb0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
19fc0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
19fd0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
19fe0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19ff0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1a000 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1a010 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1a020 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1a030 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1a040 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1a050 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1a060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a070 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1a080 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1a090 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1a0a0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1a0b0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1a0c0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1a0d0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1a0e0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1a0f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1a100 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a110 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a120 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1a130 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1a140 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1a150 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a160 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1a170 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1a180 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1a190 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1a1a0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1a1b0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1a1c0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1a1d0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1a1e0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1a1f0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1a200 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1a210 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1a220 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1a230 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1a240 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1a250 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1a260 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1a270 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1a280 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1a290 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1a2a0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1a2b0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1a2c0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1a2d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1a2e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a2f0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1a300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a310 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1a320 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1a330 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1a340 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1a350 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1a360 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1a370 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1a380 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1a390 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1a3a0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1a3b0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1a3c0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1a3d0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1a3e0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1a3f0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1a400 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1a410 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1a420 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1a430 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1a440 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1a450 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1a460 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1a470 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1a480 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1a490 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1a4a0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1a4b0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1a4c0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1a4d0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1a4e0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1a4f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1a500 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1a510 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1a520 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1a530 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1a540 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1a550 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1a560 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1a570 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1a580 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1a590 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1a5a0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1a5b0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1a5c0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1a5d0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1a5e0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1a5f0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1a600 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1a610 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1a620 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1a630 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1a640 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1a650 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1a660 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1a670 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1a680 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1a690 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1a6a0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1a6b0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1a6c0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1a6d0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1a6e0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1a6f0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1a700 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1a710 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1a720 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1a730 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1a740 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1a750 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1a760 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1a770 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1a780 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1a790 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1a7a0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1a7b0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1a7c0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1a7d0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1a7e0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1a7f0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1a800 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1a810 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1a820 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1a830 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1a840 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1a850 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1a860 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1a870 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1a880 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1a890 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1a8a0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1a8b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a8c0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1a8d0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1a8e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a8f0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1a900 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1a910 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1a920 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1a930 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1a940 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1a950 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1a960 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1a970 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1a980 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a990 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1a9a0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1a9b0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1a9c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a9d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a9e0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1a9f0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1aa00 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1aa10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1aa20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1aa30 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1aa40 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1aa50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1aa60 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1aa70 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1aa80 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1aa90 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1aaa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1aab0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1aac0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1aad0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1aae0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1aaf0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1ab00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1ab10 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1ab20 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1ab30 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1ab40 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1ab50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1ab60 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1ab70 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1ab80 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1ab90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1aba0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1abb0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1abc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1abd0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1abe0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1abf0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1ac00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1ac10 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1ac20 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1ac30 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1ac40 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1ac50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ac60 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1ac70 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1ac80 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1ac90 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1aca0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1acb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1acc0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1acd0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1ace0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1acf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ad00 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1ad10 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1ad20 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1ad30 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1ad40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1ad50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1ad60 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1ad70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1ad80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1ad90 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1ada0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1adb0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1adc0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1add0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1ade0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1adf0 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1ae00 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1ae10 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1ae20 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1ae30 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1ae40 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1ae50 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1ae60 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1ae70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ae80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ae90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1aea0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1aeb0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1aec0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1aed0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1aee0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1aef0 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1af00 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1af10 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1af20 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1af30 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1af40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1af50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1af60 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1af70 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1af80 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1af90 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1afa0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1afb0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1afc0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1afd0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1afe0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1aff0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1b000 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1b010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1b020 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1b030 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1b040 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1b050 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1b060 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1b070 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1b080 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1b090 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1b0a0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1b0b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1b0c0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1b0d0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1b0e0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1b0f0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1b100 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1b110 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1b120 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1b130 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1b140 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b150 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1b160 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1b170 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1b180 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1b190 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1b1a0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1b1b0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1b1c0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1b1d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1b1e0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1b1f0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1b200 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1b210 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1b220 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1b230 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1b240 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b250 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1b260 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1b270 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1b280 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1b290 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1b2a0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1b2b0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1b2c0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1b2d0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1b2e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1b2f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b300 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1b310 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1b320 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1b330 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1b340 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1b350 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1b360 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1b370 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1b380 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1b390 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1b3a0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1b3b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b3c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b3d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1b3e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1b3f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1b400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b410 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1b420 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1b430 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1b440 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b450 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b460 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1b470 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1b480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b4a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b4b0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1b4c0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1b4d0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b4e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b4f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b500 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1b510 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b540 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b550 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1b560 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1b570 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1b580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b590 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b5a0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1b5b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1b5c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b5d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b5e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1b5f0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1b600 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b610 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b630 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1b640 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1b650 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b680 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1b690 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1b6a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b6b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b6c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b6d0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1b6e0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1b6f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b720 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1b730 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1b740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b770 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1b780 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1b790 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b7a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b7b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7c0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1b7d0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1b7e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b7f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b810 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1b820 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1b830 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1b840 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b860 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1b870 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1b880 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1b890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b8a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b8b0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1b8c0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1b8d0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b8e0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b8f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b900 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1b910 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1b920 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b930 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b940 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1b950 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b960 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1b970 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b980 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b990 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1b9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1b9b0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1b9c0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1b9d0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1b9e0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1b9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1ba00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ba10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1ba20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ba30 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1ba40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1ba50 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1ba60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ba70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ba80 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1ba90 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1baa0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1bab0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bad0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1bae0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1baf0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bb00 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1bb10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bb20 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1bb30 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1bb40 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1bb50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1bb60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bb70 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1bb80 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1bb90 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1bba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bbb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bbc0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1bbd0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1bbe0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1bbf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1bc00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bc10 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1bc20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1bc30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1bc40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bc50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bc60 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1bc70 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1bc80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1bc90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1bca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bcb0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1bcc0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1bcd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1bce0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1bcf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bd00 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1bd10 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1bd20 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1bd30 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1bd40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1bd50 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1bd60 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1bd70 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1bd80 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1bd90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1bda0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1bdb0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1bdc0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1bdd0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1bde0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1bdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1be00 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1be10 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1be20 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1be30 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1be40 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1be50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1be60 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1be70 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1be80 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1be90 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1bea0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1beb0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1bec0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1bed0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1bee0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1bef0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1bf00 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1bf10 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1bf20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1bf30 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1bf40 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1bf50 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1bf60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1bf70 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1bf80 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1bf90 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1bfa0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1bfb0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1bfc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1bfd0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1bfe0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1bff0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1c000 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1c010 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1c020 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1c030 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1c040 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1c050 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1c060 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1c070 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1c080 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1c090 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1c0a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
1c0b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c0c0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1c0d0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1c0e0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1c0f0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1c100 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1c110 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1c120 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1c130 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1c140 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1c150 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1c160 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1c170 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1c180 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1c190 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1c1a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c1b0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1c1c0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1c1d0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1c1e0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1c1f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1c200 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1c210 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1c220 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1c230 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1c240 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1c250 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1c260 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1c270 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1c280 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1c290 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1c2a0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1c2b0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1c2c0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1c2d0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1c2e0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1c2f0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1c300 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1c310 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1c320 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1c330 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
1c340 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1c350 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1c360 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1c370 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1c380 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
1c390 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1c3a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c3b0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1c3c0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1c3d0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1c3e0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1c3f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1c400 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1c410 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1c420 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1c430 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1c440 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1c450 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1c460 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1c470 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1c480 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1c490 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1c4a0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1c4b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1c4c0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1c4d0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1c4e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c4f0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1c500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1c510 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1c520 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1c530 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1c540 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1c550 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1c560 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1c570 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1c580 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1c590 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1c5a0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1c5b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c5c0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1c5d0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1c5e0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1c5f0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1c600 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1c610 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1c620 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1c630 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1c640 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1c650 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
1c660 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1c670 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1c680 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1c690 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1c6a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c6b0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1c6c0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1c6d0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1c6e0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1c6f0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1c700 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1c710 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1c720 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1c730 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1c740 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1c750 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1c760 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1c770 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1c780 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1c790 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c7a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1c7b0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1c7c0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1c7d0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1c7e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1c7f0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1c800 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1c810 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1c820 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1c830 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c840 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1c850 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1c860 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1c870 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1c880 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1c890 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1c8a0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1c8b0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1c8c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c8d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1c8e0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1c8f0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1c900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1c910 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1c920 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1c930 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1c940 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
1c950 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c960 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1c970 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1c980 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1c990 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1c9a0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1c9b0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
1c9c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c9d0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1c9e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
1c9f0 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
1ca00 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
1ca10 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1ca20 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1ca30 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1ca40 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1ca50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1ca60 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1ca70 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1ca80 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1ca90 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1caa0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1cab0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1cac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1cad0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1cae0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1caf0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1cb00 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1cb10 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1cb20 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1cb30 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1cb40 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1cb50 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1cb60 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1cb70 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1cb80 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1cb90 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1cba0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1cbb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1cbc0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1cbd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1cbe0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1cbf0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1cc00 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1cc10 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1cc20 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1cc30 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1cc40 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1cc50 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1cc60 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1cc70 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1cc80 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1cc90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1cca0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1ccb0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1ccc0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1ccd0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1cce0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1ccf0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1cd00 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1cd10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1cd20 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1cd30 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1cd40 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1cd50 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1cd60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1cd70 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1cd80 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1cd90 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1cda0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1cdb0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1cdc0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1cdd0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1cde0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1cdf0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1ce00 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1ce10 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1ce20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ce30 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1ce40 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1ce50 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1ce60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1ce70 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1ce80 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1ce90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1cea0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ceb0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1cec0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1ced0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1cee0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1cef0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1cf00 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1cf10 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1cf20 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1cf30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cf40 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1cf50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1cf60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1cf70 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1cf80 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1cf90 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1cfa0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1cfb0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1cfc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1cfd0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1cfe0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1cff0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1d000 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1d010 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1d020 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
1d030 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1d040 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
1d050 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1d060 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1d070 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1d080 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d090 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1d0a0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1d0b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d0c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1d0d0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1d0e0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1d0f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d100 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d110 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1d120 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1d130 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1d140 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1d150 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1d160 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1d170 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1d180 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1d190 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1d1a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1d1b0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1d1c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1d1d0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1d1e0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1d1f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d200 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d210 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d220 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
1d230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1d240 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
1d250 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d260 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1d270 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
1d280 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
1d290 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
1d2a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
1d2b0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
1d2c0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
1d2d0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
1d2e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1d2f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1d300 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
1d310 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1d320 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1d330 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1d340 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1d350 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1d360 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1d370 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
1d380 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
1d390 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
1d3a0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
1d3b0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
1d3c0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
1d3d0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1d3e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
1d3f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d400 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
1d410 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
1d420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d430 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
1d440 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
1d450 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1d460 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
1d470 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
1d480 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
1d490 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
1d4a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1d4b0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
1d4c0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
1d4d0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
1d4e0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
1d4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d500 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
1d510 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1d520 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
1d530 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
1d540 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
1d550 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
1d560 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1d570 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
1d580 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
1d590 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1d5a0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1d5b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d5c0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
1d5d0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
1d5e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1d5f0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
1d600 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
1d610 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1d620 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
1d630 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1d640 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
1d650 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
1d660 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1d670 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1d680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d690 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
1d6a0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
1d6b0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
1d6c0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
1d6d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
1d6e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
1d6f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d700 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d710 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1d720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
1d730 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
1d740 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
1d750 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1d760 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
1d770 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1d780 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
1d790 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
1d7a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1d7b0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1d7c0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1d7d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1d7e0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1d7f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d800 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
1d810 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
1d820 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1d830 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
1d840 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
1d850 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1d860 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
1d870 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1d880 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1d890 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1d8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d8b0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1d8c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d8d0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1d8e0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1d8f0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1d900 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1d910 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1d920 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1d930 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1d940 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1d950 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1d960 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1d970 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1d980 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1d990 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1d9a0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1d9b0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1d9c0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1d9d0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1d9e0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1d9f0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
1da00 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1da10 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
1da20 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
1da30 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1da40 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
1da50 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1da60 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1da70 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1da80 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1da90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1daa0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1dab0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1dac0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
1dad0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
1dae0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
1daf0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
1db00 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
1db10 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
1db20 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
1db30 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
1db40 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
1db50 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
1db60 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
1db70 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
1db80 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
1db90 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1dba0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1dbb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1dbc0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
1dbd0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
1dbe0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1dbf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
1dc00 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
1dc10 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
1dc20 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
1dc30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
1dc40 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
1dc50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
1dc60 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
1dc70 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
1dc80 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
1dc90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
1dca0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
1dcb0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
1dcc0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
1dcd0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
1dce0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
1dcf0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
1dd00 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
1dd10 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
1dd20 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
1dd30 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
1dd40 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
1dd50 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
1dd60 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
1dd70 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1dd80 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
1dd90 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
1dda0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
1ddb0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
1ddc0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
1ddd0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
1dde0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
1ddf0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
1de00 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
1de10 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
1de20 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
1de30 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
1de40 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
1de50 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
1de60 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
1de70 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
1de80 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
1de90 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
1dea0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
1deb0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
1dec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
1ded0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
1dee0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
1def0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
1df00 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
1df10 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
1df20 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
1df30 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
1df40 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
1df50 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
1df60 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
1df70 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
1df80 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
1df90 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
1dfa0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
1dfb0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
1dfc0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1dfd0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
1dfe0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
1dff0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
1e000 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
1e010 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
1e020 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
1e030 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
1e040 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
1e050 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
1e060 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
1e070 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
1e080 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
1e090 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
1e0a0 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
1e0b0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
1e0c0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
1e0d0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
1e0e0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
1e0f0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
1e100 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
1e110 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
1e120 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
1e130 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
1e140 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
1e150 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
1e160 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
1e170 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
1e180 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1e190 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
1e1a0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
1e1b0 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
1e1c0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
1e1d0 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
1e1e0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
1e1f0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
1e200 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1e210 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
1e220 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
1e230 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
1e240 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
1e250 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
1e260 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1e270 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
1e280 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
1e290 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
1e2a0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
1e2b0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
1e2c0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
1e2d0 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
1e2e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1e2f0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
1e300 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
1e310 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
1e320 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
1e330 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
1e340 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
1e350 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
1e360 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
1e370 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1e380 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e390 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
1e3a0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
1e3b0 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
1e3c0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1e3d0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
1e3e0 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a  "ro", "rw" or.**
1e3f0 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65       "rwc". Atte
1e400 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
1e410 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
1e420 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29  lue is an error)
1e430 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
1e440 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
1e450 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1e460 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1e470 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
1e480 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
1e490 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
1e4a0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1e4b0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
1e4c0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
1e4d0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
1e4e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
1e4f0 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
1e500 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1e510 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
1e520 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
1e530 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1e540 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
1e550 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
1e560 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
1e570 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
1e580 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
1e590 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
1e5a0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
1e5b0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
1e5c0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
1e5d0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1e5e0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
1e5f0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1e600 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
1e610 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e620 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  E. ^If sqlite3_o
1e630 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20  pen_v2() is .** 
1e640 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20      used, it is 
1e650 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
1e660 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20  ify a value for 
1e670 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
1e680 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20  er that is .**  
1e690 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74     less restrict
1e6a0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
1e6b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
1e6c0 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74  lags passed as t
1e6d0 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20  he third .**    
1e6e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1e6f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
1e700 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
1e710 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1e720 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1e730 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
1e740 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
1e750 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
1e760 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
1e770 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1e780 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
1e790 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1e7a0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
1e7b0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
1e7c0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
1e7d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1e7e0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
1e7f0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
1e800 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
1e810 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
1e820 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
1e830 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1e840 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
1e850 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
1e860 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1e870 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
1e880 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
1e890 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
1e8a0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
1e8b0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
1e8c0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
1e8d0 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
1e8e0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
1e8f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1e900 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
1e910 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e920 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
1e930 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
1e940 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
1e950 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e960 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1e970 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
1e980 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
1e990 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1e9a0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
1e9b0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
1e9c0 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
1e9d0 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
1e9e0 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
1e9f0 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
1ea00 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
1ea10 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
1ea20 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1ea30 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1ea40 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
1ea50 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
1ea60 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
1ea70 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
1ea80 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
1ea90 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
1eaa0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
1eab0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
1eac0 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
1ead0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
1eae0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
1eaf0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
1eb00 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1eb10 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1eb20 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
1eb30 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
1eb40 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
1eb50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1eb60 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
1eb70 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
1eb80 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1eb90 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
1eba0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
1ebb0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1ebc0 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
1ebd0 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
1ebe0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
1ebf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1ec00 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
1ec10 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
1ec20 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1ec30 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
1ec40 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
1ec50 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
1ec60 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
1ec70 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
1ec80 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
1ec90 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
1eca0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
1ecb0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
1ecc0 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
1ecd0 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
1ece0 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
1ecf0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1ed00 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
1ed10 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
1ed20 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
1ed30 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
1ed40 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
1ed50 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
1ed60 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
1ed70 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
1ed80 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
1ed90 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
1eda0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
1edb0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
1edc0 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
1edd0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1ede0 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
1edf0 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
1ee00 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
1ee10 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
1ee20 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
1ee30 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
1ee40 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
1ee50 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
1ee60 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1ee70 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
1ee80 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
1ee90 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1eea0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
1eeb0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
1eec0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1eed0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
1eee0 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
1eef0 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
1ef00 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
1ef10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1ef20 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
1ef30 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
1ef40 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
1ef50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
1ef60 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
1ef70 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1ef80 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
1ef90 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
1efa0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
1efb0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
1efc0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
1efd0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
1efe0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
1eff0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
1f000 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
1f010 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
1f020 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
1f030 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
1f040 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
1f050 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
1f060 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
1f070 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
1f080 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
1f090 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
1f0a0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
1f0b0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
1f0c0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
1f0d0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
1f0e0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
1f0f0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
1f100 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
1f110 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
1f120 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
1f130 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
1f140 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
1f150 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
1f160 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
1f170 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
1f180 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
1f190 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
1f1a0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
1f1b0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
1f1c0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
1f1d0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
1f1e0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
1f1f0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1f200 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1f210 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1f220 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1f230 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f240 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1f250 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1f260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1f270 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1f280 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1f290 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1f2a0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1f2b0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1f2c0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1f2d0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1f2e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1f2f0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1f300 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1f310 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1f320 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1f330 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
1f340 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1f350 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1f360 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1f370 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1f380 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1f390 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1f3a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1f3b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1f3c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1f3d0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1f3e0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1f3f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1f400 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1f410 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1f420 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1f430 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1f440 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1f450 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f460 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1f470 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1f480 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1f490 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1f4a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1f4b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1f4c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1f4d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1f4f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1f500 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1f510 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1f520 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1f530 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1f540 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
1f550 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
1f560 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69  meters.**.** Thi
1f570 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 72  s is a utility r
1f580 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 74  outine, useful t
1f590 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
1f5a0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
1f5b0 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ks.** to see if 
1f5c0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
1f5d0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
1f5e0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
1f5f0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
1f600 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
1f610 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
1f620 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65 72  alue of the quer
1f630 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
1f640 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65  ** The zFilename
1f650 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1f660 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
1f670 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
1f680 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74  e xOpen().** met
1f690 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d 70  hod of a VFS imp
1f6a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1f6b0 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 6e  e zParam argumen
1f6c0 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  t is the name of
1f6d0 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 61   the.** query pa
1f6e0 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b 2e  rameter we seek.
1f6f0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72    This routine r
1f700 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
1f710 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a   of the zParam.*
1f720 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
1f730 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74 68  t exists.  If th
1f740 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65 73  e parameter does
1f750 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69 73   not exist, this
1f760 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75   routine.** retu
1f770 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f780 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
1f790 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d   zFilename argum
1f7a0 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ent to this func
1f7b0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f  tion is not a po
1f7c0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
1f7d0 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 6f  e.** passed into
1f7e0 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20 6d   the xOpen VFS m
1f7f0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
1f800 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
1f810 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75   routine.** is u
1f820 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
1f830 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
1f840 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
1f850 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
1f860 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
1f870 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
1f880 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
1f890 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  m);.../*.** CAPI
1f8a0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1f8b0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
1f8c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f8d0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1f8e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1f8f0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1f900 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1f910 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f920 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1f930 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1f940 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1f950 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1f960 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1f970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1f980 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1f990 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1f9a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1f9b0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1f9c0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1f9d0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1f9e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1f9f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
1fa00 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1fa10 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1fa20 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1fa30 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1fa40 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1fa50 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1fa60 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1fa70 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1fa80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1fa90 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1faa0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1fab0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1fac0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1fad0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1fae0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1faf0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1fb00 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1fb10 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1fb20 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1fb30 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
1fb40 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1fb50 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1fb60 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1fb70 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1fb80 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1fb90 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1fba0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1fbb0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1fbc0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1fbd0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1fbe0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1fbf0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1fc00 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1fc10 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1fc20 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1fc30 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
1fc40 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
1fc50 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1fc60 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
1fc70 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
1fc80 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
1fc90 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
1fca0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
1fcb0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1fcc0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
1fcd0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
1fce0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
1fcf0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
1fd00 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
1fd10 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
1fd20 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
1fd30 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
1fd40 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
1fd50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
1fd60 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
1fd70 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
1fd80 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
1fd90 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
1fda0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
1fdb0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
1fdc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1fdd0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
1fde0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1fdf0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
1fe00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1fe10 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
1fe20 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
1fe30 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
1fe40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1fe50 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
1fe60 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
1fe70 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
1fe80 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
1fe90 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
1fea0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
1feb0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1fec0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1fed0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1fee0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1fef0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1ff00 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1ff10 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1ff20 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1ff30 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1ff40 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1ff50 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1ff60 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
1ff70 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1ff80 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
1ff90 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1ffa0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
1ffb0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
1ffc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
1ffd0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
1ffe0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1fff0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
20000 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
20010 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
20020 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
20030 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
20040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
20050 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
20060 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
20070 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
20080 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
20090 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
200a0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
200b0 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
200c0 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
200d0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
200e0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
200f0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
20100 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
20110 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
20120 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
20130 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
20140 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
20150 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
20160 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
20170 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
20180 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
20190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
201a0 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
201b0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
201c0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
201d0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
201e0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
201f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
20200 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
20210 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
20220 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
20230 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
20240 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
20250 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
20260 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
20270 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
20280 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20290 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
202a0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
202b0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
202c0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
202d0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
202e0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
202f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20300 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
20310 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
20320 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
20330 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
20340 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
20350 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20360 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
20370 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
20380 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
20390 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
203a0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
203b0 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
203c0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
203d0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
203e0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
203f0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
20400 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
20410 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
20420 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
20430 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
20440 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
20450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
20460 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
20470 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
20480 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
20490 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
204a0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
204b0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
204c0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
204d0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
204e0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
204f0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
20500 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
20510 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
20520 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
20530 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
20540 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
20550 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
20560 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
20570 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
20580 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
20590 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
205a0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
205b0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
205c0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
205d0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
205e0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
205f0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
20600 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
20610 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
20620 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
20630 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
20640 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
20650 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
20660 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
20670 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
20680 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
20690 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
206a0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
206b0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
206c0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
206d0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
206e0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
206f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20700 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
20710 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
20720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
20730 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
20740 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
20750 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
20760 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
20770 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
20780 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
20790 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
207a0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
207b0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
207c0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
207d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
207e0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
207f0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
20800 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
20810 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
20820 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
20830 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
20840 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
20850 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
20860 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
20870 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
20880 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
20890 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
208a0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
208b0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
208c0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
208d0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
208e0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
208f0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
20900 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
20910 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
20920 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
20930 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
20940 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
20950 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
20960 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
20970 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
20980 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
20990 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
209a0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
209b0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
209c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
209d0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
209e0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
209f0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
20a00 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
20a10 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
20a20 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
20a30 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
20a40 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
20a50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20a60 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
20a70 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
20a80 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
20a90 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
20aa0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
20ab0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
20ac0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
20ad0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
20ae0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
20af0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20b00 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
20b10 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
20b20 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
20b30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
20b40 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
20b50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
20b60 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
20b70 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
20b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20b90 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
20ba0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
20bb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
20bc0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
20bd0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
20be0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
20bf0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
20c00 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
20c10 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
20c20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
20c30 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
20c40 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
20c50 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
20c60 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
20c70 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
20c80 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
20c90 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
20ca0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
20cb0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
20cc0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
20cd0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
20ce0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
20cf0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
20d00 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
20d10 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
20d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20d30 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
20d40 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
20d50 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
20d60 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
20d70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20d80 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20d90 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20da0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20db0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20dc0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
20dd0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
20de0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
20df0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20e00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20e10 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
20e20 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
20e30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20e40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
20e50 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
20e60 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
20e70 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
20e80 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
20e90 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
20ea0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
20eb0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
20ec0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
20ed0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
20ee0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
20ef0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20f00 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20f10 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20f20 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20f30 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20f40 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
20f50 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
20f60 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
20f70 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
20f80 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
20f90 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
20fa0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
20fb0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
20fc0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
20fd0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20fe0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
20ff0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
21000 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
21010 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
21020 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
21030 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
21040 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
21050 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
21060 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
21070 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
21080 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
21090 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
210a0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
210b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
210c0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
210d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
210e0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
210f0 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
21100 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
21110 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
21120 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
21130 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21140 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
21150 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
21160 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
21170 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
21180 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
21190 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
211a0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
211b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
211c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
211d0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
211e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
211f0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
21200 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21210 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
21220 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
21230 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
21240 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
21250 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
21260 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
21270 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
21280 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
21290 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
212a0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
212b0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
212c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
212d0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
212e0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
212f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21300 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
21310 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
21320 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
21330 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
21340 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
21350 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
21360 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
21370 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
21380 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
21390 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
213a0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
213b0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
213c0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
213d0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
213e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
213f0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
21400 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
21410 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
21420 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
21430 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
21440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21450 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
21460 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
21470 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
21480 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
21490 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
214a0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
214b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
214c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
214d0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
214e0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
214f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
21500 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
21510 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
21520 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
21530 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
21540 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
21550 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
21560 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
21570 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
21580 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21590 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
215a0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
215b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
215c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
215d0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
215e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
215f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
21600 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
21610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
21620 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
21630 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
21640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21650 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
21660 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
21670 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
21680 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
21690 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
216a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
216b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
216c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
216d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
216e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
216f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
21700 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
21710 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
21720 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
21730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
21740 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
21750 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
21760 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
21770 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
21780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
21790 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
217a0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
217b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
217c0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
217d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
217e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
217f0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
21800 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
21810 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
21820 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
21830 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
21840 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
21850 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
21860 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21870 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
21880 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
21890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
218a0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
218b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
218c0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
218d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
218e0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
218f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
21900 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
21910 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
21920 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
21930 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
21940 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
21950 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
21960 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
21970 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
21980 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
21990 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
219a0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
219b0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
219c0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
219d0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
219e0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
219f0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
21a00 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
21a10 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
21a20 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
21a30 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
21a40 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
21a50 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
21a60 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
21a70 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
21a80 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
21a90 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
21aa0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
21ab0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
21ac0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
21ad0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
21ae0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
21af0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
21b00 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
21b10 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
21b20 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
21b30 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
21b40 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
21b50 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
21b60 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
21b70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
21b80 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
21b90 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
21ba0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
21bb0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
21bc0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
21bd0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
21be0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
21bf0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
21c00 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
21c10 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
21c20 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21c30 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
21c40 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
21c50 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
21c60 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
21c70 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
21c80 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
21c90 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
21ca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21cb0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
21cc0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
21cd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
21ce0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
21cf0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
21d00 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
21d10 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
21d20 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
21d30 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
21d40 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
21d50 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
21d60 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
21d70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
21d80 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
21d90 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
21da0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
21db0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
21dc0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
21dd0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
21de0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21df0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
21e00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
21e10 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
21e20 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
21e30 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
21e40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
21e50 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
21e60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21e70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
21e80 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
21e90 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21ea0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
21eb0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
21ec0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
21ed0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21ee0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
21ef0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
21f00 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
21f10 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
21f20 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
21f30 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
21f40 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
21f50 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
21f60 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
21f70 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
21f80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
21f90 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
21fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
21fb0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
21fc0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
21fd0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
21fe0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
21ff0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
22000 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
22010 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
22020 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
22030 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
22040 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
22050 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
22060 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
22070 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
22080 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
22090 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
220a0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
220b0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
220c0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
220d0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
220e0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
220f0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
22100 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
22110 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
22120 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
22130 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
22140 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
22150 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
22160 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22170 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
22180 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
22190 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
221a0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
221b0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
221c0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
221d0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
221e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
221f0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
22200 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
22210 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
22220 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
22230 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
22240 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
22250 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
22260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22270 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
22280 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
22290 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
222a0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
222b0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
222c0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
222d0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
222e0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
222f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22300 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
22310 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
22320 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
22330 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
22340 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
22350 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
22360 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
22370 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
22380 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
22390 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
223a0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
223b0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
223c0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
223d0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
223e0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
223f0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
22400 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
22410 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
22420 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
22430 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
22440 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
22450 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
22460 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
22470 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
22480 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
22490 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
224a0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
224b0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
224c0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
224d0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
224e0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
224f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
22500 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
22510 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
22520 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
22530 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
22540 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
22550 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
22560 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
22570 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
22580 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
22590 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
225a0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
225b0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
225c0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
225d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
225e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
225f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
22600 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
22610 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
22620 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
22630 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
22640 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
22650 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
22660 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22670 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22680 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
22690 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
226a0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
226b0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
226c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
226d0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
226e0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
226f0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22700 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
22710 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22720 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
22730 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
22740 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
22750 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
22760 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22770 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22780 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22790 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
227a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
227b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
227c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
227d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
227e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
227f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22800 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22810 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
22820 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
22830 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
22840 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
22850 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
22860 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
22870 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
22880 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
22890 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
228a0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
228b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
228c0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
228d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
228e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
228f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22900 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
22910 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
22920 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
22930 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22940 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22950 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
22960 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22970 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22980 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22990 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
229a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
229b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
229c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
229d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
229e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
229f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22a00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22a10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
22a20 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
22a30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
22a40 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
22a50 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
22a60 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22a70 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22a80 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22a90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22aa0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
22ab0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22ac0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22ad0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22af0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
22b00 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
22b10 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
22b20 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
22b30 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
22b40 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
22b50 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
22b60 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
22b70 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
22b80 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
22b90 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
22ba0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
22bb0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22bc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22bd0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22be0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
22bf0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22c00 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
22c10 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
22c30 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
22c40 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
22c50 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
22c60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22c70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
22c80 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
22c90 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
22ca0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
22cb0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
22cc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22cd0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
22ce0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
22cf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
22d00 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22d10 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
22d20 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
22d30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
22d40 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
22d50 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
22d60 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
22d70 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
22d80 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
22d90 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
22da0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
22db0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
22dc0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
22dd0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
22de0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
22df0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
22e00 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
22e10 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
22e20 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
22e30 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
22e40 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
22e50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
22e60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
22e70 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
22e80 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
22e90 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
22ea0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
22eb0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
22ec0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
22ed0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
22ee0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
22ef0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
22f00 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
22f10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
22f20 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
22f30 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
22f40 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
22f50 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
22f60 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
22f70 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
22f80 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
22f90 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
22fa0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
22fb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
22fc0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
22fd0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
22fe0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
22ff0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
23000 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
23010 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
23020 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
23030 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
23040 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
23050 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
23060 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
23070 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
23080 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
23090 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
230a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
230b0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
230c0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
230d0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
230e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
230f0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
23100 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
23110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
23120 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
23130 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
23140 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
23150 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23160 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
23170 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
23180 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
23190 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
231a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
231b0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
231c0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
231d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
231e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
231f0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
23200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
23210 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
23220 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
23230 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
23240 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
23250 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
23260 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
23270 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
23280 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
23290 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
232a0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
232b0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
232c0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
232d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
232e0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
232f0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
23300 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
23310 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
23320 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
23330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23340 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
23350 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
23360 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
23370 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
23380 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
23390 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
233a0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
233b0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
233c0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
233d0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
233e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
233f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
23400 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
23410 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
23420 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
23430 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
23440 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
23450 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
23460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23470 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
23480 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
23490 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
234a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
234b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
234c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
234d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
234e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
234f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
23500 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23510 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
23520 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
23530 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
23540 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23550 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
23560 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
23570 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
23580 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
23590 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
235a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
235b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
235c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
235d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
235e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
235f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
23600 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
23610 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
23620 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
23630 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
23640 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
23650 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
23660 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
23670 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
23680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
23690 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
236a0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
236b0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
236c0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
236d0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
236e0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
236f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
23700 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
23710 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
23720 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
23730 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
23740 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
23750 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
23760 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
23770 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
23780 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
23790 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
237a0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
237b0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
237c0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
237d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
237e0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
237f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
23800 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
23810 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
23820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
23830 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
23840 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
23850 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
23860 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
23870 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
23880 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23890 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
238a0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
238b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
238c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
238d0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
238e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
238f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
23900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
23910 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
23920 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
23930 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
23940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23950 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
23960 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
23970 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
23980 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
23990 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
239a0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
239b0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
239c0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
239d0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
239e0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
239f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23a00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
23a10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
23a20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
23a30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
23a40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
23a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23a60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23a70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
23a80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
23a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
23aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
23ab0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
23ac0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
23ad0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
23ae0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
23af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
23b00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
23b10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
23b20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
23b30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
23b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
23b50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
23b60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
23b70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
23b80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
23b90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
23ba0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
23bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
23bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
23bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
23be0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
23bf0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
23c00 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
23c10 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
23c20 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
23c30 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
23c40 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
23c50 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
23c60 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
23c70 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
23c80 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
23c90 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
23ca0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
23cb0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
23cc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23cd0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
23ce0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
23cf0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
23d00 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
23d10 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
23d20 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
23d30 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
23d40 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
23d50 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
23d60 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
23d70 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
23d80 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
23d90 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
23da0 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
23db0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
23dc0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
23dd0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
23de0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
23df0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
23e00 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
23e10 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
23e20 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
23e30 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
23e40 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
23e50 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
23e60 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
23e70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
23e80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
23e90 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
23ea0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
23eb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
23ec0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
23ed0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
23ee0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
23ef0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
23f00 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
23f10 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
23f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
23f30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
23f40 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
23f50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
23f60 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
23f70 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
23f80 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
23f90 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
23fa0 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
23fb0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
23fc0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
23fd0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
23fe0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
23ff0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
24000 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
24010 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
24020 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
24030 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
24040 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
24050 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
24060 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
24070 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
24080 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
24090 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
240a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
240b0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
240c0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
240d0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
240e0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
240f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
24100 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
24110 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
24120 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
24130 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
24140 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
24150 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24160 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
24170 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
24180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
24190 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
241a0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
241b0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
241c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
241d0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
241e0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
241f0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
24200 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
24210 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
24220 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
24230 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
24240 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
24250 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
24260 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
24270 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
24280 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
24290 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
242a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
242b0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
242c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
242d0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
242e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
242f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
24300 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
24310 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  or..** If a non-
24320 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
24330 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
24340 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
24350 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
24360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
24370 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
24380 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
24390 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
243a0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
243b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
243c0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
243d0 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
243e0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
243f0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
24400 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
24410 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
24420 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
24430 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
24440 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
24450 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
24460 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
24470 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
24480 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
24490 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
244a0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
244b0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
244c0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
244d0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
244e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
244f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
24500 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
24510 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
24520 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
24530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
24540 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
24550 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
24560 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
24570 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
24580 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
24590 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
245a0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
245b0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
245c0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
245d0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
245e0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
245f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
24600 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
24610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
24620 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
24630 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
24640 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
24650 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
24660 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
24670 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
24680 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
24690 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
246a0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
246b0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
246c0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
246d0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
246e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
246f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
24700 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
24710 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
24720 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
24730 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
24740 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
24750 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
24760 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
24770 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
24780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24790 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
247a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
247b0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
247c0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
247d0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
247e0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
247f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
24800 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
24810 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
24820 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
24830 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
24840 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
24850 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
24860 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
24870 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
24880 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
24890 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
248a0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
248b0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
248c0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
248d0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
248e0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
248f0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
24900 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
24910 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
24920 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
24930 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
24940 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
24950 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
24960 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
24970 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
24980 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
24990 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
249a0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
249b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
249c0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
249d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249e0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
249f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
24a00 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
24a10 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
24a20 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
24a30 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
24a40 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
24a50 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
24a60 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
24a70 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
24a80 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
24a90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24aa0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
24ab0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
24ac0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
24ad0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24ae0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
24af0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
24b00 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
24b10 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
24b20 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
24b30 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
24b40 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
24b50 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
24b60 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
24b70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
24b80 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
24b90 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
24ba0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
24bb0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
24bc0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
24bd0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
24be0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
24bf0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24c00 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
24c10 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
24c20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
24c30 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
24c40 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
24c50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24c60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24c70 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
24c80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24c90 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
24ca0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
24cb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
24cc0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
24cd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
24ce0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24cf0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
24d00 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
24d10 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
24d20 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
24d30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24d40 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
24d50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24d60 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
24d70 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
24d80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
24d90 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
24da0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
24db0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
24dc0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
24dd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24de0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
24df0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
24e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
24e10 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
24e20 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
24e30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
24e40 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
24e50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24e60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
24e70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
24e80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24e90 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
24ea0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
24eb0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
24ec0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24ed0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
24ee0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24ef0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
24f00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
24f10 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
24f20 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
24f30 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
24f40 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
24f50 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
24f60 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
24f70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24f80 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
24f90 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
24fa0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
24fb0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
24fc0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
24fd0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
24fe0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
24ff0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
25000 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
25010 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
25020 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
25030 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
25040 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
25050 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
25060 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
25070 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
25080 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
25090 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
250a0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
250b0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
250c0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
250d0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
250e0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
250f0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
25100 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
25110 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
25120 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
25130 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
25140 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
25150 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25160 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25170 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
25180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25190 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
251a0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
251b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
251c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
251d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
251e0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
251f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
25200 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25210 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
25220 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
25230 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
25240 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25250 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
25260 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
25270 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
25280 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
25290 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
252a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
252b0 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
252c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
252d0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
252e0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
252f0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
25300 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
25310 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
25320 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
25330 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
25340 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
25350 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
25360 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
25370 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
25380 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
25390 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
253a0 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
253b0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
253c0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
253d0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
253e0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
253f0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
25400 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
25410 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
25420 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
25430 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
25440 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
25450 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
25460 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
25470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
25480 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
25490 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
254a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
254b0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
254c0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
254d0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
254e0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
254f0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
25500 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
25510 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
25520 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
25530 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
25540 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
25550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25560 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25580 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25590 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
255a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
255b0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
255c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
255d0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
255e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
255f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25600 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
25610 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
25620 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
25630 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25640 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
25650 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
25660 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
25670 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
25680 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
25690 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
256a0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
256b0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
256c0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
256d0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
256e0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
256f0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
25700 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
25710 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25720 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
25730 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
25740 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
25750 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
25760 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
25770 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
25780 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
25790 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
257a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
257b0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
257c0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
257d0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
257e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
257f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
25800 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
25810 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
25820 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
25830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25840 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25850 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25860 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25870 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
25890 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
258a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
258b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
258c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
258d0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
258e0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
258f0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
25900 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
25910 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
25920 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
25930 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
25940 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
25950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25960 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
25970 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25980 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
25990 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
259a0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
259b0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
259c0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
259d0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
259e0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
259f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25a00 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
25a10 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
25a20 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
25a30 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
25a40 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
25a50 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
25a60 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
25a70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25a80 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
25a90 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
25aa0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
25ab0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
25ac0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
25ad0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
25ae0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
25af0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25b00 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
25b10 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
25b20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
25b30 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
25b40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25b50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
25b60 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
25b70 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
25b80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
25b90 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
25ba0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
25bb0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
25bc0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
25bd0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
25be0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
25bf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
25c00 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
25c10 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
25c20 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
25c30 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
25c40 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
25c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
25c60 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
25c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
25c80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
25c90 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
25ca0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
25cb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
25cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25cd0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
25ce0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
25cf0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
25d00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25d10 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
25d20 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
25d30 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
25d40 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
25d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
25d60 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
25d70 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
25d80 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
25d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25da0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
25db0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
25dc0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
25dd0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
25de0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
25df0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
25e00 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
25e10 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25e20 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
25e30 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
25e40 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
25e50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
25e60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
25e70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
25e80 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
25e90 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
25ea0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
25eb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
25ec0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
25ed0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
25ee0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
25ef0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
25f00 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
25f10 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
25f20 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
25f30 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
25f40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
25f50 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
25f60 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
25f70 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
25f80 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
25f90 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
25fa0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
25fb0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
25fc0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
25fd0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
25fe0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
25ff0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
26000 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
26010 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
26020 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
26030 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
26040 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26050 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
26060 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26070 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
26080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26090 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
260a0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
260b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
260c0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
260d0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
260e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
260f0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
26100 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
26110 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
26120 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
26130 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
26140 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
26150 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
26160 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
26170 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
26180 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
26190 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
261a0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
261b0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
261c0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
261d0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
261e0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
261f0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
26200 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
26210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
26220 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
26230 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
26240 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
26250 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
26260 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
26270 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
26280 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
26290 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
262a0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
262b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
262c0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
262d0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
262e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
262f0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
26300 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
26310 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
26320 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
26330 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
26340 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
26350 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
26360 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
26370 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
26380 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
26390 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
263a0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
263b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
263c0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
263d0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
263e0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
263f0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
26400 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
26410 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
26420 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
26430 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
26440 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
26450 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
26460 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
26470 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
26480 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
26490 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
264a0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
264b0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
264c0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
264d0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
264e0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
264f0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
26500 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
26510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
26520 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
26530 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
26540 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
26550 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
26560 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
26570 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
26580 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
26590 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
265a0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
265b0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
265c0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
265d0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
265e0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
265f0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
26600 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
26610 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
26620 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26630 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
26640 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
26650 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
26660 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
26670 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
26680 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
26690 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
266a0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
266b0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
266c0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
266d0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
266e0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
266f0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
26700 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
26710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
26720 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
26730 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
26740 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
26750 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
26760 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
26770 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
26780 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
26790 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
267a0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
267b0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
267c0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
267d0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
267e0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
267f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
26800 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
26810 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
26820 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
26830 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26840 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
26850 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
26860 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
26870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
26880 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
26890 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
268a0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
268b0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
268c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
268d0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
268e0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
268f0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
26900 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
26910 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
26920 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
26930 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
26940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26950 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
26960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26970 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
26980 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26990 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
269a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
269b0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
269c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
269d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
269e0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
269f0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
26a00 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
26a10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
26a20 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
26a30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26a40 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
26a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
26a60 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
26a70 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
26a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26a90 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
26aa0 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
26ab0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
26ac0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26ad0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
26ae0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
26af0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
26b00 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
26b10 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
26b20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
26b30 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
26b40 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
26b50 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
26b60 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
26b70 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
26b80 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
26b90 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
26ba0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
26bb0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
26bc0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
26bd0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
26be0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
26bf0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
26c00 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
26c10 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
26c20 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
26c30 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
26c40 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
26c50 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
26c60 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
26c70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
26c80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
26c90 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
26ca0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
26cb0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
26cc0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
26cd0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
26ce0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
26cf0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
26d00 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
26d10 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
26d20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
26d30 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
26d40 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
26d50 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
26d60 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
26d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
26d80 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
26d90 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
26da0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
26db0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
26dc0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
26dd0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
26de0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
26df0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
26e00 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
26e10 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
26e20 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
26e30 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
26e40 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
26e50 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
26e60 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
26e70 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
26e80 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
26e90 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
26ea0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
26eb0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
26ec0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
26ed0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
26ee0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
26ef0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
26f00 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
26f10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26f20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
26f30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
26f40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
26f50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26f60 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
26f70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26f80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26f90 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
26fa0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
26fb0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
26fc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26fd0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
26fe0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
26ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
27000 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
27010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27020 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
27030 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
27040 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
27050 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
27060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27070 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
27080 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
27090 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
270a0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
270b0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
270c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
270d0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
270e0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
270f0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
27100 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
27110 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
27120 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
27130 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
27140 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
27150 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
27160 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
27170 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
27180 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
27190 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
271a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
271b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
271c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
271d0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
271e0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
271f0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
27200 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
27210 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
27220 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
27230 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
27240 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
27250 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
27260 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
27270 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
27280 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
27290 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
272a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
272b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
272c0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
272d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
272e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
272f0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
27300 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
27310 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
27320 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
27330 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
27340 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
27350 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
27360 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
27370 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
27380 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
27390 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
273a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
273b0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
273c0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
273d0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
273e0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
273f0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
27400 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
27410 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
27420 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
27430 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
27440 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
27450 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
27460 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
27470 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
27480 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
27490 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
274a0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
274b0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
274c0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
274d0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
274e0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
274f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
27500 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
27510 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
27520 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
27530 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
27540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
27550 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
27560 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
27570 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
27580 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
27590 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
275a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
275b0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
275c0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
275d0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
275e0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
275f0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
27600 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
27610 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
27620 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
27630 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
27640 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
27650 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
27660 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
27670 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
27680 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
27690 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
276a0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
276b0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
276c0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
276d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
276e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
276f0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
27700 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
27710 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
27720 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
27730 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
27740 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
27750 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
27760 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
27770 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
27780 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
27790 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
277a0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
277b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
277c0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
277d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
277e0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
277f0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
27800 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
27810 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
27820 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
27830 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
27840 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
27850 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
27860 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
27870 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
27880 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
27890 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
278a0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
278b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
278c0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
278d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
278e0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
278f0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
27900 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
27910 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
27920 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
27930 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
27940 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
27950 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
27960 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
27970 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
27980 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
27990 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
279a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
279b0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
279c0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
279d0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
279e0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
279f0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
27a00 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
27a10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
27a20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
27a30 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
27a40 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
27a50 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
27a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
27a70 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
27a80 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
27a90 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
27aa0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
27ab0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
27ac0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
27ad0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
27ae0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
27af0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
27b00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
27b10 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
27b20 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
27b30 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
27b40 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
27b50 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
27b60 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
27b70 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
27b80 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
27b90 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
27ba0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
27bb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
27bc0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
27bd0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
27be0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
27bf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
27c00 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
27c10 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
27c20 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
27c30 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
27c40 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
27c50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27c60 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
27c70 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
27c80 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
27c90 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
27ca0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
27cb0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
27cc0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
27cd0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
27ce0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
27cf0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
27d00 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
27d10 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
27d20 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
27d30 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
27d40 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
27d50 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
27d60 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
27d70 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
27d80 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
27d90 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
27da0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
27db0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
27dc0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
27dd0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
27de0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
27df0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
27e00 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
27e10 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
27e20 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
27e30 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
27e40 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
27e50 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
27e60 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
27e70 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
27e80 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
27e90 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
27ea0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27eb0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
27ec0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
27ed0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
27ee0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
27ef0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
27f00 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
27f10 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
27f20 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
27f30 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
27f40 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
27f50 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
27f60 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
27f70 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
27f80 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
27f90 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
27fa0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
27fb0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27fc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27fd0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
27fe0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
27ff0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
28000 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
28010 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28020 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
28030 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
28040 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
28050 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
28060 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
28070 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
28080 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
28090 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
280a0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
280b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
280c0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
280d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
280e0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
280f0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
28100 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
28110 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
28120 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
28130 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
28140 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28150 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
28160 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
28170 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
28180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28190 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
281a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
281b0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
281c0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
281d0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
281e0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
281f0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
28200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
28210 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
28220 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
28230 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
28240 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
28250 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28260 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
28270 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
28280 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
28290 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
282a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
282b0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
282c0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
282d0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
282e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
282f0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
28300 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
28310 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28320 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
28330 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
28340 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
28350 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
28360 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
28370 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
28380 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
28390 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
283a0 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
283b0 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
283c0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
283d0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
283e0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
283f0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
28400 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
28410 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
28420 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28430 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28440 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
28450 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
28460 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
28470 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28480 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
28490 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
284a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
284b0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
284c0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
284d0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
284e0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
284f0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
28500 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28510 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
28520 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
28530 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
28540 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
28550 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
28560 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
28570 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
28580 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
28590 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
285a0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
285b0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
285c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
285d0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
285e0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
285f0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
28600 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
28610 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
28620 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
28630 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
28640 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
28650 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
28660 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
28670 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
28680 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
28690 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
286a0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
286b0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
286c0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
286d0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
286e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
286f0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
28700 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
28710 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
28720 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
28730 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
28740 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
28750 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
28760 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
28770 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
28780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
28790 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
287a0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
287b0 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
287c0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
287d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
287e0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
287f0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
28800 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
28810 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
28820 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
28830 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
28840 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
28850 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
28860 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
28870 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
28880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28890 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
288a0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
288b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
288c0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
288d0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
288e0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
288f0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
28900 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
28910 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
28920 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
28930 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
28940 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
28950 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
28960 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
28970 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
28980 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
28990 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
289a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
289b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
289c0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
289d0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
289e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
289f0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
28a00 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
28a10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28a20 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
28a30 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
28a40 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
28a50 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
28a60 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
28a70 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
28a80 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
28a90 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
28aa0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
28ab0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
28ac0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
28ad0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
28ae0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28af0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
28b00 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
28b10 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
28b20 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
28b30 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
28b40 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
28b50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
28b60 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
28b70 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
28b80 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
28b90 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
28ba0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
28bb0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
28bc0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28bd0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
28be0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28bf0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
28c00 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
28c10 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
28c20 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
28c30 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
28c40 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
28c50 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
28c60 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
28c70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28c80 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
28c90 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
28ca0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
28cb0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
28cc0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
28cd0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
28ce0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
28cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
28d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
28d10 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
28d20 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
28d30 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
28d40 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
28d50 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
28d60 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
28d70 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
28d80 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
28d90 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
28da0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
28db0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
28dc0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
28dd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
28de0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
28df0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
28e00 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
28e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28e20 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
28e30 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
28e40 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
28e50 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
28e60 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
28e70 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
28e80 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
28e90 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
28ea0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
28eb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
28ec0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
28ed0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
28ee0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
28ef0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
28f00 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
28f10 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
28f20 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
28f30 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
28f40 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
28f50 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
28f60 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
28f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28f80 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
28f90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
28fa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28fb0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
28fc0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
28fd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
28fe0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
28ff0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
29000 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
29010 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
29020 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
29030 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
29040 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
29050 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29060 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
29070 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
29080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
29090 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
290a0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
290b0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
290c0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
290d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
290e0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
290f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
29100 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
29110 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
29120 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
29130 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
29140 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
29150 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
29160 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
29170 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
29180 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
29190 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
291a0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
291b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
291c0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
291d0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
291e0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
291f0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
29200 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
29210 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29220 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
29230 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
29240 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
29250 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
29260 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
29270 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
29280 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
29290 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
292a0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
292b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
292c0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
292d0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
292e0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
292f0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
29300 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
29310 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
29320 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
29330 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
29340 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
29350 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
29360 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
29370 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
29380 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
29390 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
293a0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
293b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
293c0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
293d0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
293e0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
293f0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
29400 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
29410 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
29420 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
29430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29440 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
29450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29460 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
29470 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
29480 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
29490 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
294a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
294b0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
294c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
294d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
294e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
294f0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
29500 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
29510 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
29520 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
29530 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
29540 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
29550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
29560 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
29570 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
29580 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
29590 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
295a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
295b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
295c0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
295d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
295e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
295f0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
29600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29610 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
29620 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
29630 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
29640 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29650 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
29660 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
29670 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29680 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
29690 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
296a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
296b0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
296c0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
296d0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
296e0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
296f0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
29700 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
29710 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
29720 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
29730 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
29740 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
29750 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
29760 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
29770 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
29780 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
29790 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
297a0 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
297b0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
297c0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
297d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
297e0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
297f0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
29800 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
29810 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
29820 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
29830 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
29840 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
29850 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
29860 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
29870 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
29880 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
29890 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
298a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
298b0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
298c0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
298d0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
298e0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
298f0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
29900 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
29910 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
29920 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29930 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
29940 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
29950 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
29960 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
29970 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
29980 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29990 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
299a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
299b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
299c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
299d0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
299e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
299f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
29a00 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
29a10 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29a20 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
29a30 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
29a40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
29a50 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
29a60 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
29a70 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
29a80 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
29a90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
29aa0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
29ab0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
29ac0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
29ad0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
29ae0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
29af0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
29b00 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
29b10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
29b20 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
29b30 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
29b40 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
29b50 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
29b60 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
29b70 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
29b80 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
29b90 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
29ba0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
29bb0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
29bc0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
29bd0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
29be0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
29bf0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
29c00 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
29c10 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29c20 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
29c30 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
29c40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
29c50 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
29c60 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
29c70 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
29c80 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
29c90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
29ca0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
29cb0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
29cc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
29cd0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
29ce0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
29cf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
29d00 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
29d10 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
29d20 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
29d30 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
29d40 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
29d50 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
29d60 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
29d70 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
29d80 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
29d90 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
29da0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
29db0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
29dc0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
29dd0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
29de0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
29df0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
29e00 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
29e10 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
29e20 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
29e30 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
29e40 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
29e50 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
29e60 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
29e70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
29e80 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
29e90 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
29ea0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
29eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29ec0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
29ed0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
29ee0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
29ef0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
29f00 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
29f10 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
29f20 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
29f30 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
29f40 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
29f50 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
29f60 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
29f70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
29f80 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
29f90 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
29fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29fb0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
29fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29fd0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
29fe0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
29ff0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2a000 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2a010 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2a020 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2a030 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2a040 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2a050 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2a060 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2a070 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2a080 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a090 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2a0a0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2a0b0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2a0c0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2a0d0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2a0e0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2a0f0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2a100 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2a110 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2a120 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2a130 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2a140 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2a150 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2a160 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2a170 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2a180 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2a190 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2a1a0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2a1b0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2a1c0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2a1d0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2a1e0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2a1f0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2a200 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2a210 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2a220 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2a230 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2a240 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2a250 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2a260 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2a270 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2a280 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2a290 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2a2a0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2a2b0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2a2c0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2a2d0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2a2e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2a2f0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2a300 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2a310 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2a320 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2a330 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2a340 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2a350 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2a360 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2a370 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2a380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a390 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2a3a0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2a3b0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2a3c0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2a3d0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2a3e0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2a3f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2a400 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2a410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a420 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2a430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a440 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2a450 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2a460 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2a470 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2a480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a490 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2a4a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2a4b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a4c0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2a4d0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2a4e0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2a4f0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2a500 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2a510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a520 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2a530 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2a540 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2a550 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2a560 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2a570 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2a580 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2a590 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2a5a0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2a5b0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2a5c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a5d0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2a5e0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2a5f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2a600 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2a610 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2a620 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2a630 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2a640 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2a650 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2a660 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2a670 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2a680 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2a690 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2a6a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2a6b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2a6c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a6d0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2a6e0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2a6f0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2a700 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2a710 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2a720 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2a730 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2a740 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2a750 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
2a760 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2a770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a780 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2a790 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2a7a0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2a7b0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2a7c0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2a7d0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2a7e0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2a7f0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2a800 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2a810 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2a820 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2a830 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2a840 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2a850 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2a860 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2a870 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2a880 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2a890 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2a8a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2a8b0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2a8c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2a8d0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2a8e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a8f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2a900 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a920 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2a930 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a940 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a950 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2a960 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a970 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2a980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a990 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2a9a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2a9b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a9c0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2a9d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a9e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a9f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2aa00 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2aa10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2aa20 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2aa30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2aa40 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2aa50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2aa60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2aa70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2aa80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2aa90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2aaa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2aab0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2aac0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2aad0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2aae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2aaf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ab00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2ab10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2ab20 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2ab30 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2ab40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2ab60 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2ab70 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2ab80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ab90 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2aba0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2abb0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2abc0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2abd0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2abe0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2abf0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2ac00 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2ac10 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2ac20 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2ac30 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2ac40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2ac50 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2ac60 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2ac70 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2ac80 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2ac90 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2aca0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2acb0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2acc0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2acd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ace0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2acf0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2ad00 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2ad10 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2ad20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2ad30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad40 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2ad50 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2ad60 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2ad70 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2ad80 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2ad90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2ada0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2adb0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2adc0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2add0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2ade0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2adf0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2ae00 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2ae10 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2ae20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ae30 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2ae40 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2ae50 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2ae60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2ae70 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2ae80 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2ae90 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2aea0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2aeb0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2aec0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2aed0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2aee0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2aef0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2af00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2af10 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2af20 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2af30 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2af40 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2af50 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2af60 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2af70 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2af80 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2af90 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2afa0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2afb0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2afc0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
2afd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2afe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2aff0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b000 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2b010 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2b020 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2b030 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2b040 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2b050 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2b060 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b070 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2b080 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2b090 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2b0a0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2b0b0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2b0c0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2b0d0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2b0e0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2b0f0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2b100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b110 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2b120 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2b130 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2b140 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2b150 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2b160 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2b170 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2b180 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b190 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2b1a0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2b1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b1c0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2b1d0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2b1e0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2b1f0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2b200 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2b210 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2b220 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2b230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b240 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2b250 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2b260 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2b270 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2b280 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2b290 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2b2a0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2b2b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b2c0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2b2d0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2b2e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b2f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2b300 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2b310 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2b320 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2b330 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2b340 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2b350 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2b360 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2b370 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2b380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2b390 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2b3a0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2b3b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2b3c0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2b3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b3e0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2b3f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b400 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2b410 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2b420 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b430 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b440 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2b450 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2b460 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2b470 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2b480 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2b490 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b4a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b4b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2b4c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b4d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b4e0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2b4f0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2b500 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2b510 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2b520 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2b530 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2b540 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2b550 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2b560 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2b570 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2b580 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2b590 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2b5a0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2b5b0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2b5c0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2b5d0 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2b5e0 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2b5f0 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2b600 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2b610 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b620 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2b630 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2b640 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2b650 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2b660 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2b670 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2b680 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2b690 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2b6a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2b6b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b6c0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2b6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2b6e0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2b6f0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2b700 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2b710 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2b720 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2b730 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b740 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2b750 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b760 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b770 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2b780 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2b790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2b7a0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2b7b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2b7c0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2b7d0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2b7e0 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2b7f0 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2b800 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2b810 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2b820 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2b830 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2b840 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2b850 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2b860 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2b870 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2b880 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2b890 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2b8a0 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2b8b0 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2b8c0 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2b8d0 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2b8e0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2b8f0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2b900 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2b910 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2b920 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2b930 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b940 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2b950 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2b960 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b970 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2b980 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2b990 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2b9a0 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2b9b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2b9c0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2b9d0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2b9e0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2b9f0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2ba00 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2ba10 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2ba20 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2ba30 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2ba40 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2ba50 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2ba60 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2ba70 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2ba80 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2ba90 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2baa0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2bab0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2bac0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2bad0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2bae0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2baf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2bb00 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2bb10 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2bb20 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2bb30 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2bb40 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2bb50 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2bb60 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2bb70 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2bb80 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2bb90 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2bba0 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2bbb0 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2bbc0 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2bbd0 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2bbe0 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2bbf0 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2bc00 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2bc10 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2bc20 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2bc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bc40 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2bc50 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2bc60 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2bc70 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2bc80 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2bc90 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2bca0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2bcb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2bcc0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2bcd0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2bce0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2bcf0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2bd00 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2bd10 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2bd20 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2bd30 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2bd40 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2bd50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2bd60 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2bd70 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2bd80 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2bd90 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
2bda0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
2bdb0 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
2bdc0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
2bdd0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2bde0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2bdf0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2be00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2be10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2be20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2be30 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2be40 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2be50 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
2be60 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
2be70 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
2be80 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2be90 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2bea0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2beb0 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2bec0 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2bed0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2bee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2bef0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
2bf00 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2bf10 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2bf20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2bf30 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2bf40 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
2bf50 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
2bf60 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2bf70 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2bf80 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2bf90 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
2bfa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2bfb0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2bfc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2bfd0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2bfe0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
2bff0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2c000 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
2c010 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2c020 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2c030 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2c040 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
2c050 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
2c060 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2c070 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
2c080 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
2c090 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2c0a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c0b0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
2c0c0 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
2c0d0 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
2c0e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2c0f0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
2c100 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
2c110 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
2c120 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
2c130 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
2c140 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
2c150 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
2c160 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c170 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
2c180 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
2c190 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
2c1a0 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
2c1b0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2c1c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2c1d0 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
2c1e0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
2c1f0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
2c200 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
2c210 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
2c220 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
2c230 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2c240 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
2c250 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
2c260 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
2c270 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
2c280 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
2c290 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2c2a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2c2b0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
2c2c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2c2d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2c2e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2c2f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2c300 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2c310 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2c320 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2c330 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2c340 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2c350 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2c360 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2c370 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
2c380 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2c390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
2c3a0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
2c3b0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2c3c0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2c3d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2c3e0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
2c3f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2c400 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
2c410 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
2c420 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
2c430 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
2c440 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2c450 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
2c460 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
2c470 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
2c480 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
2c490 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2c4a0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
2c4b0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2c4c0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
2c4d0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2c4e0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2c4f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2c500 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
2c510 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c520 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2c530 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
2c540 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
2c550 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
2c560 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
2c570 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2c580 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2c590 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
2c5a0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
2c5b0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
2c5c0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
2c5d0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
2c5e0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
2c5f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2c600 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
2c610 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
2c620 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c630 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2c640 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
2c650 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
2c660 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
2c670 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
2c680 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
2c690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c6a0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
2c6b0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2c6c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2c6d0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
2c6e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2c6f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c700 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c710 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c720 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c730 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2c740 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2c750 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2c760 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2c770 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2c780 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c790 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c7a0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2c7b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c7c0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c7d0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c7e0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2c7f0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2c800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c810 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2c820 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2c830 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2c840 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2c850 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2c860 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2c870 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2c880 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c890 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c8a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c8b0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2c8c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c8d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c8e0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2c8f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c900 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2c910 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c920 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2c930 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2c940 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2c950 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2c960 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2c970 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2c980 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2c990 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2c9a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2c9b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2c9c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c9d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c9e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c9f0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2ca00 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
2ca10 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2ca20 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2ca30 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2ca40 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
2ca50 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2ca60 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2ca70 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2ca80 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2ca90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2caa0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2cab0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2cac0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2cad0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2cae0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2caf0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2cb00 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2cb10 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2cb20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2cb30 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2cb40 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2cb50 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2cb60 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2cb70 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2cb80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cb90 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2cba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2cbb0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2cbc0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2cbd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2cbe0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2cbf0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2cc00 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2cc10 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2cc20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2cc30 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2cc40 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2cc50 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2cc60 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2cc70 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2cc80 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2cc90 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2cca0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2ccb0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2ccc0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ccd0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2cce0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2ccf0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2cd00 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2cd10 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2cd20 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2cd30 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2cd40 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2cd50 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
2cd60 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
2cd70 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
2cd80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2cd90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
2cda0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2cdb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2cdc0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2cdd0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2cde0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2cdf0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2ce00 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ce10 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
2ce20 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2ce30 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
2ce40 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2ce50 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ce60 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
2ce70 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
2ce80 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2ce90 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2cea0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2ceb0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2cec0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
2ced0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
2cee0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2cef0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
2cf00 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2cf10 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
2cf20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2cf30 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2cf40 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2cf50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
2cf60 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
2cf70 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
2cf80 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2cf90 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
2cfa0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
2cfb0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
2cfc0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
2cfd0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
2cfe0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
2cff0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
2d000 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
2d010 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
2d020 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
2d030 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
2d040 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
2d050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d060 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2d070 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d080 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2d090 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
2d0a0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2d0b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2d0c0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2d0d0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
2d0e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
2d0f0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
2d100 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2d110 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
2d120 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d130 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
2d140 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
2d150 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2d160 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
2d170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
2d180 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
2d190 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2d1a0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
2d1b0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
2d1c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d1d0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
2d1e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d1f0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
2d200 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d210 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d220 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
2d230 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
2d240 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
2d250 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d260 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
2d270 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
2d280 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
2d290 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2d2a0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2d2b0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2d2c0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2d2d0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d2e0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2d2f0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2d300 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2d310 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d320 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d330 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2d340 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2d350 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2d360 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2d370 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2d380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d390 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2d3a0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2d3b0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
2d3c0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2d3d0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2d3e0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2d3f0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
2d400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d410 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2d420 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2d430 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2d440 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2d450 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2d460 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2d470 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2d480 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
2d490 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2d4a0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
2d4b0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2d4c0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
2d4d0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
2d4e0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
2d4f0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
2d500 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
2d510 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
2d520 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
2d530 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
2d540 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
2d550 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
2d560 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
2d570 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
2d580 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
2d590 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
2d5a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
2d5b0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
2d5c0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
2d5d0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
2d5e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
2d5f0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
2d600 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
2d610 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
2d620 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2d630 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2d640 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2d650 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
2d660 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
2d670 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
2d680 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
2d690 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
2d6a0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2d6b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d6c0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2d6d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
2d6e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
2d6f0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
2d700 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
2d710 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
2d720 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2d730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d740 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
2d750 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
2d760 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d770 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2d780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d790 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
2d7a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2d7b0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2d7c0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2d7d0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2d7e0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2d7f0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2d800 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2d810 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
2d820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2d830 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
2d840 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2d850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d860 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
2d870 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2d880 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
2d890 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
2d8a0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2d8b0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2d8c0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2d8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2d8e0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2d8f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2d900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2d910 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
2d920 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
2d930 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2d940 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
2d950 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2d960 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d990 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2d9a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d9b0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
2d9c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2d9d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2d9e0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2d9f0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2da00 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2da10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2da20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2da30 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2da40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2da50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2da60 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
2da70 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
2da80 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
2da90 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
2daa0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2dab0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
2dac0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
2dad0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
2dae0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
2daf0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
2db00 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
2db10 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2db20 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
2db30 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
2db40 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
2db50 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
2db60 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
2db70 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
2db80 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
2db90 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
2dba0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2dbb0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2dbc0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
2dbd0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2dbe0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2dbf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2dc00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2dc10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2dc20 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2dc30 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
2dc40 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
2dc50 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
2dc60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2dc70 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
2dc80 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
2dc90 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
2dca0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
2dcb0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
2dcc0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
2dcd0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
2dce0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
2dcf0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
2dd00 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
2dd10 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
2dd20 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
2dd30 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
2dd40 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2dd50 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
2dd60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
2dd70 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
2dd80 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
2dd90 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
2dda0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
2ddb0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ddc0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
2ddd0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
2dde0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
2ddf0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
2de00 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
2de10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
2de20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2de30 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
2de40 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2de50 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
2de60 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
2de70 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
2de80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2de90 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
2dea0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
2deb0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
2dec0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
2ded0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2dee0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
2def0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2df00 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
2df10 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
2df20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
2df30 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
2df40 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
2df50 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2df60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2df70 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
2df80 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
2df90 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
2dfa0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
2dfb0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
2dfc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
2dfd0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
2dfe0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
2dff0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
2e000 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
2e010 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e020 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
2e030 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
2e040 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
2e050 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2e060 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
2e070 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2e080 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2e090 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2e0a0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2e0b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2e0c0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
2e0d0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
2e0e0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2e0f0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2e100 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
2e110 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2e120 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
2e130 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2e140 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2e150 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2e160 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
2e170 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2e180 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2e190 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e1a0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2e1b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2e1c0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2e1d0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2e1e0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
2e1f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e200 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2e210 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e220 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2e230 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2e240 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2e250 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2e260 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2e270 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2e280 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e290 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2e2a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e2b0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2e2c0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2e2d0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2e2e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e2f0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2e300 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2e310 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2e320 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2e330 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2e340 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2e350 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e360 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2e370 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2e380 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
2e390 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2e3a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e3b0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2e3c0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
2e3d0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
2e3e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e3f0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
2e400 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2e410 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2e420 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
2e430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e440 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
2e450 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2e460 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e470 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2e480 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2e490 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2e4a0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2e4b0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2e4c0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2e4d0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2e4e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
2e4f0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2e500 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2e510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e520 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e530 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2e540 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
2e550 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2e560 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2e570 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2e580 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2e590 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2e5a0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2e5b0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2e5c0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2e5d0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2e5e0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2e5f0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2e600 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2e610 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2e620 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2e630 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2e640 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2e650 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2e660 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2e670 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2e680 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2e690 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2e6a0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2e6b0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2e6c0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2e6d0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2e6e0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2e6f0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2e700 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2e710 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2e720 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2e730 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2e740 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2e750 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2e760 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2e770 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2e780 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2e790 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2e7a0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2e7b0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2e7c0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2e7d0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2e7e0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2e7f0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2e800 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2e810 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2e820 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2e830 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2e840 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e850 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2e860 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2e870 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2e880 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2e890 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2e8a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2e8b0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2e8c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e8d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
2e8e0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2e8f0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2e900 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2e910 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2e920 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2e930 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2e940 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2e950 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2e960 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2e970 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2e980 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2e990 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2e9a0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2e9b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2e9c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
2e9d0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2e9e0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
2e9f0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
2ea00 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
2ea10 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2ea20 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
2ea30 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2ea40 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2ea50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ea60 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2ea70 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2ea80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2ea90 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2eaa0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2eab0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2eac0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
2ead0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
2eae0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2eaf0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2eb00 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
2eb10 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
2eb20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2eb30 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
2eb40 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
2eb50 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
2eb60 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2eb70 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
2eb80 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
2eb90 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
2eba0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
2ebb0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
2ebc0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
2ebd0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
2ebe0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
2ebf0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
2ec00 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
2ec10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
2ec20 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2ec30 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
2ec40 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
2ec50 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
2ec60 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2ec70 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2ec80 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
2ec90 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
2eca0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
2ecb0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
2ecc0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2ecd0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2ece0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2ecf0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2ed00 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2ed10 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2ed20 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2ed30 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
2ed40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
2ed50 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2ed60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2ed70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2ed80 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2ed90 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2eda0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2edb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2edc0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2edd0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
2ede0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
2edf0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2ee00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
2ee10 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
2ee20 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
2ee30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
2ee40 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
2ee50 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
2ee60 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
2ee70 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2ee80 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
2ee90 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
2eea0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
2eeb0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
2eec0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
2eed0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2eee0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
2eef0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
2ef00 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
2ef10 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
2ef20 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
2ef30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
2ef40 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
2ef50 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
2ef60 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
2ef70 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2ef80 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
2ef90 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
2efa0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
2efb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2efc0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
2efd0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
2efe0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
2eff0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
2f000 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
2f010 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2f020 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
2f030 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
2f040 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
2f050 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
2f060 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
2f070 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
2f080 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
2f090 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
2f0a0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
2f0b0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
2f0c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2f0d0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
2f0e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
2f0f0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
2f100 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2f110 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
2f120 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
2f130 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2f140 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
2f150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f160 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
2f170 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
2f180 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
2f190 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2f1a0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
2f1b0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2f1c0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
2f1d0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
2f1e0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2f1f0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
2f200 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f210 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2f220 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f230 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
2f240 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2f250 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2f260 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
2f270 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
2f280 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
2f290 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
2f2a0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
2f2b0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
2f2c0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
2f2d0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
2f2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
2f2f0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
2f300 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2f310 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2f320 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2f330 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2f340 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f350 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
2f360 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2f370 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2f380 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f390 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f3a0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
2f3b0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
2f3c0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
2f3d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2f3e0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
2f3f0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
2f400 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
2f410 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2f420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f430 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2f440 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
2f450 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
2f460 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2f470 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f480 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
2f490 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
2f4a0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
2f4b0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
2f4c0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
2f4d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f4e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2f4f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f500 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2f510 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2f520 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2f530 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2f540 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f550 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2f560 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2f570 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2f580 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2f590 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2f5a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f5b0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2f5c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f5d0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
2f5e0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
2f5f0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
2f600 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
2f610 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
2f620 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2f630 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
2f640 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
2f650 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
2f660 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f670 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
2f680 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2f690 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
2f6a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2f6b0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
2f6c0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
2f6d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
2f6e0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2f6f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2f700 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
2f710 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2f720 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2f730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f740 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
2f750 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
2f760 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
2f770 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f780 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2f790 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2f7a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f7b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2f7c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2f7d0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
2f7e0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2f7f0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
2f800 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2f810 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2f820 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2f830 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2f840 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f850 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
2f860 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f870 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
2f880 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2f890 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
2f8a0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
2f8b0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
2f8c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f8d0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
2f8e0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
2f8f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f900 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2f910 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f920 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2f930 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
2f940 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
2f950 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
2f960 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
2f970 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
2f980 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2f990 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
2f9a0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
2f9b0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
2f9c0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
2f9d0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
2f9e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f9f0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2fa00 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2fa10 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2fa20 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2fa30 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2fa40 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2fa50 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
2fa60 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
2fa70 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
2fa80 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
2fa90 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
2faa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2fab0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2fac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fad0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
2fae0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
2faf0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
2fb00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fb10 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2fb20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2fb30 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2fb40 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2fb50 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2fb60 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2fb70 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
2fb80 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
2fb90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fba0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
2fbb0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
2fbc0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
2fbd0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
2fbe0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
2fbf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2fc00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2fc10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2fc20 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2fc30 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2fc40 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2fc50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fc60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fc70 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
2fc80 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2fc90 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2fca0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2fcb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fcc0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2fcd0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2fce0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2fcf0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2fd00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fd10 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2fd20 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2fd30 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2fd40 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2fd50 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2fd60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fd70 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
2fd80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2fd90 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2fda0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fdb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2fdc0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
2fdd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2fde0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2fdf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fe00 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
2fe10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2fe20 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2fe30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2fe40 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2fe50 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2fe60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2fe70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fe80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2fe90 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2fea0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2feb0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2fec0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2fed0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2fee0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2fef0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2ff00 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2ff10 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
2ff20 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2ff30 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2ff40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2ff50 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2ff60 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2ff70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ff80 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2ff90 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2ffa0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2ffb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ffc0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2ffd0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2ffe0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2fff0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
30000 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
30010 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
30020 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
30030 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
30040 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
30050 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
30060 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
30070 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
30080 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
30090 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
300a0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
300b0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
300c0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
300d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
300e0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
300f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30100 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
30110 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
30120 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
30130 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
30140 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
30150 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
30160 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
30170 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
30180 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
30190 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
301a0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
301b0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
301c0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
301d0 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
301e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
301f0 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
30200 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
30210 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
30220 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
30230 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
30240 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
30250 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
30260 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
30270 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
30280 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
30290 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
302a0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
302b0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
302c0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
302d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
302e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
302f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
30300 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
30310 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
30320 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
30330 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
30340 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
30350 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
30360 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
30370 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
30380 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
30390 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
303a0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
303b0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
303c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
303d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
303e0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
303f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
30400 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
30410 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
30420 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
30430 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
30440 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
30450 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
30460 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
30470 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
30480 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
30490 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
304a0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
304b0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
304c0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
304d0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
304e0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
304f0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
30500 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
30510 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
30520 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
30530 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
30540 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30550 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
30560 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
30570 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
30580 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
30590 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
305a0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
305b0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
305c0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
305d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
305e0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
305f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30600 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30610 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30620 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
30630 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30640 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30650 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
30660 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
30670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30680 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
30690 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
306a0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
306b0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
306c0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
306d0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
306e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
306f0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
30700 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
30710 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
30720 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
30730 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
30740 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
30750 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
30760 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
30770 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
30780 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
30790 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
307a0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
307b0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
307c0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
307d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
307e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
307f0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
30800 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
30810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30820 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
30830 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
30840 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
30850 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30860 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
30870 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
30880 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
30890 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
308a0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
308b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
308c0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
308d0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
308e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
308f0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
30900 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
30910 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
30920 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
30930 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30940 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
30950 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30960 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30970 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
30980 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30990 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
309a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
309b0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
309c0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
309d0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
309e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
309f0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
30a00 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
30a10 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
30a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30a30 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
30a40 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
30a50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30a60 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
30a70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30a80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30a90 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
30aa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30ab0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30ac0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
30ad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30ae0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30af0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
30b00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30b10 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
30b20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30b30 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
30b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
30b50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30b60 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
30b70 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30b80 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
30b90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
30ba0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30bb0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30bc0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30bd0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
30be0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
30bf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30c00 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
30c10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
30c20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
30c30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
30c40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30c50 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
30c60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
30c70 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
30c80 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
30c90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30ca0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
30cb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
30cc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
30cd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ce0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
30cf0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
30d00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30d10 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
30d20 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
30d30 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
30d40 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
30d50 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
30d60 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
30d70 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
30d80 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
30d90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
30da0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
30db0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
30dc0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
30dd0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
30de0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
30df0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
30e00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
30e10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
30e20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
30e30 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
30e40 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
30e50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
30e60 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
30e70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
30e80 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
30e90 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
30ea0 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
30eb0 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
30ec0 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
30ed0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
30ee0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
30ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
30f00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
30f10 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
30f20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
30f30 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
30f40 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
30f50 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
30f60 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
30f70 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
30f80 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
30f90 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
30fa0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
30fb0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
30fc0 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
30fd0 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
30fe0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
30ff0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
31000 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
31010 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
31020 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31030 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
31040 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
31050 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
31060 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
31070 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
31080 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
31090 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
310a0 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
310b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
310c0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
310d0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
310e0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
310f0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
31100 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
31110 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
31120 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
31130 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
31140 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
31150 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31160 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
31170 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
31180 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
31190 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
311a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
311b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
311c0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
311d0 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
311e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
311f0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
31200 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
31210 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
31220 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
31230 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
31240 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
31250 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
31260 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
31270 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
31280 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
31290 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
312a0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
312b0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
312c0 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
312d0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
312e0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
312f0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
31300 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
31310 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
31320 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
31330 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
31340 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
31350 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
31360 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
31370 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
31380 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
31390 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
313a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
313b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
313c0 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
313d0 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
313e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
313f0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
31400 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
31410 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
31420 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
31430 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
31440 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
31450 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
31460 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
31470 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
31480 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
31490 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
314a0 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
314b0 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
314c0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
314d0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
314e0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
314f0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
31500 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
31510 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
31520 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
31530 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
31540 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
31550 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
31560 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
31570 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
31580 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
31590 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
315a0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
315b0 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
315c0 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
315d0 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
315e0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
315f0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
31600 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
31610 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
31620 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
31630 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
31640 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
31650 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
31660 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
31670 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
31680 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
31690 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
316a0 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
316b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
316c0 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
316d0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
316e0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
316f0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
31700 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
31710 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31720 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
31730 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
31740 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
31750 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
31760 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
31770 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
31780 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
31790 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
317a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
317b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
317c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
317d0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
317e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
317f0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
31800 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
31810 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
31820 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
31830 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
31840 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
31850 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
31860 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
31870 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
31880 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
31890 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
318a0 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
318b0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
318c0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
318d0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
318e0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
318f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
31900 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
31910 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
31920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
31930 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
31940 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
31950 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
31960 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31970 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
31980 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
31990 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
319a0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
319b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
319c0 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
319d0 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
319e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
319f0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
31a00 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
31a10 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
31a20 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31a30 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
31a40 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
31a50 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
31a60 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
31a70 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
31a80 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
31a90 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
31aa0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
31ab0 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
31ac0 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
31ad0 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
31ae0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
31af0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
31b00 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
31b10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
31b20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
31b30 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
31b40 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
31b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
31b60 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
31b70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
31b80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
31b90 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31ba0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31bb0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
31bc0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
31bd0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
31be0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
31bf0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
31c00 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
31c10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31c20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
31c30 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
31c40 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
31c50 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
31c60 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
31c70 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
31c80 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
31c90 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
31ca0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
31cb0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
31cc0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
31cd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31ce0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
31cf0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
31d00 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
31d10 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
31d20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
31d30 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
31d40 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
31d50 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
31d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31d70 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
31d80 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
31d90 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
31da0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
31db0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
31dc0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
31dd0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
31de0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
31df0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
31e00 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
31e10 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
31e20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
31e30 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
31e40 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
31e50 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
31e60 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
31e70 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
31e80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
31e90 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
31ea0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
31eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
31ec0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
31ed0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
31ee0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
31ef0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
31f00 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
31f10 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
31f20 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
31f30 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
31f40 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
31f50 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
31f60 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
31f70 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
31f80 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
31f90 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
31fa0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
31fb0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
31fc0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
31fd0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
31fe0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
31ff0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
32000 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
32010 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32020 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
32030 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
32040 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
32050 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32060 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
32070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32080 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
32090 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
320a0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
320b0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
320c0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
320d0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
320e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
320f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
32100 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
32110 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
32120 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
32130 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
32140 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
32150 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
32160 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
32170 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32180 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
32190 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
321a0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
321b0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
321c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
321d0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
321e0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
321f0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
32200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
32210 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
32220 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32230 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
32240 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32260 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
32270 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
32280 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
32290 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
322a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
322b0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
322c0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
322d0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
322e0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
322f0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
32300 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
32310 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
32320 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
32330 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
32340 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
32350 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
32360 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
32370 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
32380 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
32390 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
323a0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
323b0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
323c0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
323d0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
323e0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
323f0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
32400 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
32410 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
32420 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
32430 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
32440 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
32450 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
32460 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
32470 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
32480 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
32490 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
324a0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
324b0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
324c0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
324d0 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
324e0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
324f0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
32500 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
32510 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
32520 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
32530 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
32540 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
32550 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
32560 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
32570 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
32580 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
32590 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
325a0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
325b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
325c0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
325d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
325e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
325f0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
32600 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
32610 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
32620 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
32630 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
32640 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
32650 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
32660 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
32670 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
32680 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
32690 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
326a0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
326b0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
326c0 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
326d0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
326e0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
326f0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
32700 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
32710 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
32720 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
32730 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
32740 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
32750 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
32760 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
32770 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
32780 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
32790 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
327a0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
327b0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
327c0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
327d0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
327e0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
327f0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
32800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
32810 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
32820 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
32830 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
32840 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
32850 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
32860 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
32870 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
32880 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
32890 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
328a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
328b0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
328c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
328d0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
328e0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
328f0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
32900 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
32910 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
32920 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
32930 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
32940 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
32950 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
32960 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
32970 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
32980 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
32990 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
329a0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
329b0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
329c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
329d0 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
329e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
329f0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
32a00 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
32a10 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
32a20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
32a30 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
32a40 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
32a50 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
32a60 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
32a70 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
32a80 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
32a90 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
32aa0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
32ab0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
32ac0 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
32ad0 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
32ae0 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
32af0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
32b00 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
32b10 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
32b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32b30 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
32b40 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
32b50 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
32b60 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
32b70 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
32b80 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
32b90 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
32ba0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
32bb0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
32bc0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
32bd0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
32be0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
32bf0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
32c00 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
32c10 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
32c20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
32c30 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
32c40 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
32c50 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
32c60 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
32c70 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
32c80 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
32c90 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
32ca0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
32cb0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
32cc0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
32cd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
32ce0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
32cf0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
32d00 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
32d10 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
32d20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
32d30 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
32d40 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
32d50 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
32d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
32d70 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
32d80 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
32d90 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
32da0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
32db0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
32dc0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
32dd0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
32de0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
32df0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
32e00 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
32e10 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
32e20 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
32e30 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
32e40 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
32e50 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
32e60 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
32e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
32e80 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32e90 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
32ea0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
32eb0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
32ec0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
32ed0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
32ee0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
32ef0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
32f00 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
32f10 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32f20 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
32f30 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
32f40 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
32f50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
32f60 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
32f70 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
32f80 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
32f90 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
32fa0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
32fb0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
32fc0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
32fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
32fe0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
32ff0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
33000 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
33010 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
33020 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
33030 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
33040 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
33050 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
33060 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
33070 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
33080 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
33090 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
330a0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
330b0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
330c0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
330d0 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
330e0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
330f0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
33100 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
33110 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
33120 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
33130 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
33140 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
33150 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
33160 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
33170 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
33180 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
33190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
331a0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
331b0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
331c0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
331d0 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
331e0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
331f0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
33200 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
33210 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
33220 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
33230 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
33240 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
33250 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
33260 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
33270 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
33280 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
33290 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
332a0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
332b0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
332c0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
332d0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
332e0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
332f0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
33300 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
33310 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
33320 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
33330 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
33340 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
33350 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
33360 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
33370 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
33380 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
33390 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
333a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
333b0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
333c0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
333d0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
333e0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
333f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
33400 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
33410 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
33420 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
33430 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
33440 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
33450 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
33460 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
33470 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
33480 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
33490 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
334a0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
334b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
334c0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
334d0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
334e0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
334f0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
33500 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
33510 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
33520 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
33530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33540 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
33550 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
33560 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
33570 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
33580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
33590 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
335a0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
335b0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
335c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
335d0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
335e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
335f0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
33600 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33610 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
33620 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
33630 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
33640 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
33650 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
33660 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
33670 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
33680 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
33690 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
336a0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
336b0 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20   Filename For A 
336c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
336d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
336e0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
336f0 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(D,N) interfac
33700 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
33710 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d  ter to a filenam
33720 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
33730 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20  with database N 
33740 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  of connection D.
33750 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61    ^The main data
33760 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73  base file.** has
33770 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
33780 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
33790 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  o attached datab
337a0 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74  ase N on the dat
337b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
337c0 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74  ion D, or if dat
337d0 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d  abase N is a tem
337e0 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d  porary or in-mem
337f0 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68  ory database, th
33800 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  en.** a NULL poi
33810 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
33820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c  ..**.** ^The fil
33830 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62  ename returned b
33840 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
33850 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  is the output of
33860 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74   the.** xFullPat
33870 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20  hname method of 
33880 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20  the [VFS].  ^In 
33890 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
338a0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c   filename.** wil
338b0 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65  l be an absolute
338c0 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20   pathname, even 
338d0 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  if the filename 
338e0 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20  used.** to open 
338f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69  the database ori
33900 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52  ginally was a UR
33910 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61  I or relative pa
33920 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  thname..*/.const
33930 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
33940 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
33950 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
33960 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
33970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33980 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
33990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
339a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
339b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
339c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
339d0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
339e0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
339f0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
33a00 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
33a10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33a20 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
33a30 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
33a40 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
33a50 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
33a60 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
33a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33a80 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
33a90 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
33aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
33ab0 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
33ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
33ad0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
33ae0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
33af0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
33b00 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
33b10 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
33b20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
33b30 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
33b40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
33b50 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
33b60 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
33b70 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
33b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
33b90 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
33ba0 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
33bb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
33bc0 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
33bd0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
33be0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
33bf0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33c10 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
33c20 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
33c30 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
33c40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33c50 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
33c60 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
33c70 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
33c80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
33c90 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
33ca0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
33cb0 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
33cc0 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
33cd0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
33ce0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33cf0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
33d00 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
33d10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
33d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
33d30 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
33d40 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
33d50 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
33d60 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
33d70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
33d80 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
33d90 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
33da0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
33db0 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
33dc0 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
33dd0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
33de0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
33df0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
33e00 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
33e10 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
33e20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
33e30 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
33e40 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
33e50 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
33e60 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
33e70 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
33e80 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
33e90 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
33ea0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
33eb0 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
33ec0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
33ed0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
33ee0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
33ef0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
33f00 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
33f10 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
33f20 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
33f30 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
33f40 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
33f50 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
33f60 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
33f70 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
33f80 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
33f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33fa0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
33fb0 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
33fc0 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
33fd0 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
33fe0 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64  * The commit and
33ff0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
34000 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74  allbacks are not
34010 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54   reentrant..** T
34020 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
34030 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
34040 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
34050 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
34060 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
34070 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
34080 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
34090 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
340a0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
340b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
340c0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
340d0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
340e0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
340f0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
34100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34110 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
34120 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
34130 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
34140 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
34150 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
34160 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  hat running any 
34170 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d  other SQL statem
34180 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ents, including 
34190 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
341a0 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20  s,.** or merely 
341b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
341c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
341d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
341e0 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  ()] will modify.
341f0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
34200 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
34210 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
34220 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
34230 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
34240 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
34250 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
34260 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
34270 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
34280 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
34290 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
342a0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
342b0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
342c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
342d0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
342e0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
342f0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
34300 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
34310 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
34320 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
34330 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
34340 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
34350 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
34360 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
34370 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
34380 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
34390 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
343a0 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
343b0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
343c0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
343d0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
343e0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
343f0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
34400 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
34410 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
34420 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
34430 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
34440 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
34450 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
34460 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
34470 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
34480 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
34490 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
344a0 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
344b0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
344c0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
344d0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
344e0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
344f0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
34500 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
34510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
34520 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
34530 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
34540 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
34550 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
34560 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
34570 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
34580 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
34590 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
345a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
345b0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
345c0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
345d0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
345e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
345f0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
34600 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
34610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34620 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34630 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
34640 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
34650 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
34660 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
34670 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
34680 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
34690 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
346a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
346b0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
346c0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
346d0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
346e0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
346f0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
34700 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
34710 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
34720 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
34730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
34740 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
34750 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
34760 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
34770 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
34780 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
34790 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
347a0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
347b0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
347c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
347d0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
347e0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
347f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34800 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
34810 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
34820 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
34830 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
34840 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
34850 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
34860 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
34870 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
34880 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
34890 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
348a0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
348b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
348c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
348d0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
348e0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
348f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
34900 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
34910 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34920 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
34930 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
34940 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
34950 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
34960 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
34970 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
34980 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
34990 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
349a0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
349b0 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
349c0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
349d0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
349e0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
349f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
34a00 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
34a10 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
34a20 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
34a30 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
34a40 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
34a50 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
34a60 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
34a70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
34a80 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
34a90 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
34aa0 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
34ab0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
34ac0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
34ad0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
34ae0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
34af0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
34b00 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
34b10 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
34b20 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
34b30 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
34b40 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
34b50 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
34b60 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
34b70 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
34b80 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
34b90 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
34ba0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
34bb0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
34bc0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
34bd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
34be0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
34bf0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
34c00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
34c10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
34c20 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
34c30 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
34c40 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
34c50 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
34c60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
34c70 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
34c80 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
34c90 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
34ca0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
34cb0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
34cc0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
34cd0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
34ce0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
34cf0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
34d00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34d10 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
34d20 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
34d30 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
34d40 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
34d50 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
34d60 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
34d70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
34d80 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
34d90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
34da0 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
34db0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
34dc0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
34dd0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
34de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
34df0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
34e00 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
34e10 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
34e20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
34e30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
34e40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
34e50 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
34e60 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
34e70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
34e80 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
34e90 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
34ea0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
34eb0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
34ec0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
34ed0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
34ee0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34ef0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
34f00 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
34f10 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
34f20 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
34f30 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
34f40 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
34f50 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
34f60 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
34f70 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
34f80 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
34f90 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
34fa0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
34fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
34fc0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
34fd0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34fe0 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
34ff0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
35000 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
35010 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
35020 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
35030 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
35040 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
35050 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
35060 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
35070 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
35080 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
35090 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
350a0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
350b0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
350c0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
350d0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
350e0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
350f0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
35100 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
35110 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
35120 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
35130 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
35140 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
35150 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
35160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
35170 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
35180 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
35190 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
351a0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
351b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
351c0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
351d0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
351e0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
351f0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
35200 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
35210 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
35220 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
35230 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
35240 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
35250 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
35260 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
35270 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
35280 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
35290 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
352a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
352b0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
352c0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
352d0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
352e0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
352f0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
35300 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
35310 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
35320 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
35330 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
35340 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
35350 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
35360 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
35370 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
35380 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
35390 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
353a0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
353b0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
353c0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
353d0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
353e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
353f0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
35400 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
35410 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
35420 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
35430 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
35440 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
35450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
35460 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
35470 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
35480 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
35490 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
354a0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
354b0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
354c0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
354d0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
354e0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
354f0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
35500 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
35510 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35520 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
35530 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
35540 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
35550 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
35560 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
35570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
35580 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
35590 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
355a0 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
355b0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
355c0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
355d0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
355e0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
355f0 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  NT]..**.** See a
35600 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
35610 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
35620 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
35630 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
35640 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
35650 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d  PI3REF: Free Mem
35660 6f 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61  ory Used By A Da
35670 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
35680 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
35690 69 74 65 33 5f 64 62 5f 73 68 72 69 6e 6b 28 44  ite3_db_shrink(D
356a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
356b0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61 73 20  mpts to free as 
356c0 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d 65 6d  much heap.** mem
356d0 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c 65 20  ory as possible 
356e0 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 63 6f  from database co
356f0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e 6c 69  nnection D. Unli
35700 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ke the.** [sqlit
35710 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
35720 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  y()] interface, 
35730 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
35740 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a 2a 2a  s effect even.**
35750 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51 4c 49   when then [SQLI
35760 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
35770 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63 6f 6d  _MANAGEMENT] com
35780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
35790 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64 2e 0a   is.** omitted..
357a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
357b0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
357c0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69 6e  _memory()].*/.in
357d0 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c  t sqlite3_db_rel
357e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71 6c 69  ease_memory(sqli
357f0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
35800 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
35810 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
35820 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
35830 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
35840 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72  _limit64() inter
35850 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72  face sets and/or
35860 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20   queries the.** 
35870 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68  soft limit on th
35880 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
35890 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
358a0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
358b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c   SQLite..** ^SQL
358c0 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b  ite strives to k
358d0 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20  eep heap memory 
358e0 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f  utilization belo
358f0 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a  w the soft heap.
35900 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75  ** limit by redu
35910 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20  cing the number 
35920 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e  of pages held in
35930 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a   the page cache.
35940 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72  ** as heap memor
35950 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61 63  y usages approac
35960 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a  hes the limit..*
35970 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70  * ^The soft heap
35980 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22   limit is "soft"
35990 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74 68   because even th
359a0 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72 69  ough SQLite stri
359b0 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62  ves to stay.** b
359c0 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20  elow the limit, 
359d0 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74  it will exceed t
359e0 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20  he limit rather 
359f0 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a  than generate.**
35a00 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45   an [SQLITE_NOME
35a10 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74  M] error.  In ot
35a20 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
35a30 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a  oft heap limit .
35a40 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  ** is advisory o
35a50 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
35a60 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
35a70 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  m sqlite3_soft_h
35a80 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73  eap_limit64() is
35a90 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
35aa0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35ab0 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65  mit prior to the
35ac0 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20   call.  ^If the 
35ad0 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65  argument N is ne
35ae0 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e  gative.** then n
35af0 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65  o change is made
35b00 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61   to the soft hea
35b10 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c  p limit.  Hence,
35b20 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
35b30 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74  size of the soft
35b40 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20   heap limit can 
35b50 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  be determined by
35b60 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
35b70 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
35b80 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61 20  imit64() with a 
35b90 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e  negative argumen
35ba0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
35bb0 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a   argument N is z
35bc0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66  ero then the sof
35bd0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
35be0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
35bf0 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  ^(The soft heap 
35c00 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66  limit is not enf
35c10 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75 72  orced in the cur
35c20 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
35c30 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72  ion.** if one or
35c40 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69   more of followi
35c50 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72  ng conditions ar
35c60 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e true:.**.** <u
35c70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73  l>.** <li> The s
35c80 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
35c90 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  s set to zero..*
35ca0 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63  * <li> Memory ac
35cb0 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61  counting is disa
35cc0 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d  bled using a com
35cd0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  bination of the.
35ce0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
35cf0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
35d00 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
35d10 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69  S],...) start-ti
35d20 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a  me option and.**
35d30 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54        the [SQLIT
35d40 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
35d50 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  TUS] compile-tim
35d60 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  e option..** <li
35d70 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  > An alternative
35d80 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
35d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70  ementation is sp
35da0 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a  ecified using.**
35db0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
35dc0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
35dd0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e  ONFIG_PCACHE2],.
35de0 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ..)..** <li> The
35df0 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f   page cache allo
35e00 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f  cates from its o
35e10 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73  wn memory pool s
35e20 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20  upplied.**      
35e30 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  by [sqlite3_conf
35e40 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
35e50 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e  IG_PAGECACHE],..
35e60 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a  .) rather than.*
35e70 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20  *      from the 
35e80 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  heap..** </ul>)^
35e90 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67  .**.** Beginning
35ea0 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
35eb0 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20  sion 3.7.3, the 
35ec0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35ed0 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72  is enforced.** r
35ee0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
35ef0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
35f00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
35f10 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
35f20 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
35f30 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f  e option is invo
35f40 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49  ked.  With [SQLI
35f50 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
35f60 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a  _MANAGEMENT],.**
35f70 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
35f80 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
35f90 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79   on every memory
35fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69   allocation.  Wi
35fb0 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  thout.** [SQLITE
35fc0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
35fd0 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20  ANAGEMENT], the 
35fe0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35ff0 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64  is only enforced
36000 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  .** when memory 
36010 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  is allocated by 
36020 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20  the page cache. 
36030 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74   Testing suggest
36040 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a  s that because.*
36050 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  * the page cache
36060 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e   is the predomin
36070 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20  ate memory user 
36080 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a  in SQLite, most.
36090 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
360a0 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65  will achieve ade
360b0 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20  quate soft heap 
360c0 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e  limit enforcemen
360d0 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65  t without.** the
360e0 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   use of [SQLITE_
360f0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
36100 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a  NAGEMENT]..**.**
36110 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   The circumstanc
36120 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53  es under which S
36130 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72  QLite will enfor
36140 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ce the soft heap
36150 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68   limit may.** ch
36160 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20  anges in future 
36170 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
36180 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  te..*/.sqlite3_i
36190 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66  nt64 sqlite3_sof
361a0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73  t_heap_limit64(s
361b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b  qlite3_int64 N);
361c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
361d0 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f 66  : Deprecated Sof
361e0 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74  t Heap Limit Int
361f0 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43  erface.** DEPREC
36200 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ATED.**.** This 
36210 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64 20  is a deprecated 
36220 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b  version of the [
36230 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
36240 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
36250 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69 73  interface.  This
36260 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76   routine is prov
36270 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  ided for histori
36280 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
36290 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  y.** only.  All 
362a0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
362b0 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a   should use the.
362c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  ** [sqlite3_soft
362d0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
362e0 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68 65   interface rathe
362f0 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e  r than this one.
36300 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
36310 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
36320 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
36330 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a  it(int N);.../*.
36340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
36350 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
36360 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
36370 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  A Table.**.** ^T
36380 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
36390 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
363a0 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
363b0 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
363c0 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
363d0 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
363e0 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
363f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36400 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
36410 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
36420 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
36430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75  .**.** ^The colu
36440 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
36450 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
36460 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
36470 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a   parameters to.*
36480 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
36490 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
364a0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
364b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
364c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
364d0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
364e0 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  ", or an attache
364f0 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
36500 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
36510 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
36520 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73   NULL. ^If it is
36530 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
36540 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
36550 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
36560 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
36570 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
36580 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62  algorithm used b
36590 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  y the database e
365a0 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f  ngine to.** reso
365b0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
365c0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
365d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
365e0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
365f0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
36600 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
36610 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
36620 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
36630 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
36640 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
36650 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
36660 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
36670 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
36680 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72  * ^Metadata is r
36690 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
366a0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
366b0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
366c0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
366d0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
366e0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
366f0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79  s function. ^Any
36700 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
36710 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
36720 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
36730 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
36740 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
36750 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
36760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f  ed..**.** ^(<blo
36770 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
36780 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
36790 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d  * <tr><th> Param
367a0 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74  eter <th> Output
367b0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44  <br>Type <th>  D
367c0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a  escription.**.**
367d0 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74   <tr><td> 5th <t
367e0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
367f0 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a  td> Data type.**
36800 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74   <tr><td> 6th <t
36810 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
36820 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61  td> Name of defa
36830 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
36840 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74  quence.** <tr><t
36850 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 7th <td> int 
36860 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
36870 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20  e if column has 
36880 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  a NOT NULL const
36890 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  raint.** <tr><td
368a0 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 8th <td> int  
368b0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
368c0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61   if column is pa
368d0 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  rt of the PRIMAR
368e0 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64  Y KEY.** <tr><td
368f0 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 9th <td> int  
36900 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
36910 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41   if column is [A
36920 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a  UTOINCREMENT].**
36930 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
36940 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
36950 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70  ** ^The memory p
36960 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
36970 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
36980 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
36990 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
369a0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
369b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
369c0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
369d0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
369e0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
369f0 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
36a00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
36a10 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
36a20 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
36a30 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  w, an [error cod
36a40 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
36a50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
36a60 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
36a70 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
36a80 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
36a90 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52  d an.** [INTEGER
36aa0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
36ab0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
36ac0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
36ad0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
36ae0 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
36af0 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
36b00 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
36b10 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49  ared column. ^(I
36b20 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
36b30 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
36b40 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52  ared [INTEGER PR
36b50 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
36b60 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
36b70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
36b80 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c   are set as foll
36b90 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
36ba0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
36bb0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
36bc0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
36bd0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
36be0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
36bf0 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
36c00 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
36c10 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
36c20 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a   0.** </pre>)^.*
36c30 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
36c40 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e  tion may load on
36c50 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61  e or more schema
36c60 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  s from database 
36c70 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20  files. If an.** 
36c80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
36c90 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73  ing this process
36ca0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75  , or if the requ
36cb0 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63  ested table or c
36cc0 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20  olumn.** cannot 
36cd0 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72  be found, an [er
36ce0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
36cf0 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
36d00 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a  or message left.
36d10 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ** in the [datab
36d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36d30 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
36d40 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
36d50 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a  rrmsg()).)^.**.*
36d60 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f  * ^This API is o
36d70 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
36d80 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
36d90 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
36da0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
36db0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
36dc0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
36dd0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
36de0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
36df0 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
36e00 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
36e10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36e20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
36e30 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
36e40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36e50 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
36e60 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
36e70 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
36e80 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
36e90 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
36ea0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
36eb0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
36ec0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
36ed0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
36ee0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
36ef0 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
36f00 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
36f10 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
36f20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
36f30 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
36f40 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
36f50 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
36f60 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
36f70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
36f80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
36f90 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
36fa0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
36fb0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
36fc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
36fd0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
36fe0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
36ff0 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
37000 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
37010 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
37020 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
37030 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
37040 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37050 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
37060 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  sion.**.** ^This
37070 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
37080 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
37090 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
370a0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
370b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
370c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
370d0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
370e0 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
370f0 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78   an.** SQLite ex
37100 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
37110 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
37120 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
37130 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f  ** ^The entry po
37140 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a  int is zProc..**
37150 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30   ^zProc may be 0
37160 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
37170 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37180 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64  entry point.** d
37190 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
371a0 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
371b0 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  it"..** ^The sql
371c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
371d0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
371e0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
371f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
37200 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
37210 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
37220 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
37230 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
37240 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
37250 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
37260 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
37270 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
37280 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
37290 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
372a0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
372b0 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61  with error messa
372c0 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
372d0 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61  n memory.** obta
372e0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
372f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68  e3_malloc()]. Th
37300 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
37310 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65  on.** should fre
37320 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
37330 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
37340 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
37350 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
37360 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
37370 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  led using.** [sq
37380 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
37390 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  d_extension()] p
373a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
373b0 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68  this API,.** oth
373c0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
373d0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
373e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
373f0 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
37400 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74  sion() SQL funct
37410 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ion]..*/.int sql
37420 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
37430 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
37440 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
37450 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
37460 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
37470 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37480 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37490 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
374a0 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
374b0 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
374c0 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
374d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
374e0 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
374f0 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
37500 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
37510 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
37520 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
37530 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
37540 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
37550 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
37560 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
37570 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
37580 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
37590 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  * ^So as not to 
375a0 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
375b0 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
375c0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
375d0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
375e0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
375f0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
37600 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
37610 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
37620 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
37630 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
37640 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
37650 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
37660 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f  ng API.** is pro
37670 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
37680 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
37690 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
376a0 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66  hanism on and of
376b0 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73  f..**.** ^Extens
376c0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
376d0 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53  ff by default. S
376e0 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e  ee ticket #1863.
376f0 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71  .** ^Call the sq
37700 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
37710 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
37720 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66  utine with onoff
37730 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65  ==1.** to turn e
37740 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
37750 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20   on and call it 
37760 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
37770 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b   turn.** it back
37780 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69   off again..*/.i
37790 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
377a0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
377b0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
377c0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
377d0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d   CAPI3REF: Autom
377e0 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74  atically Load St
377f0 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20  atically Linked 
37800 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Extensions.**.**
37810 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
37820 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e 74   causes the xEnt
37830 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 69  ryPoint() functi
37840 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
37850 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77   for.** each new
37860 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37870 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 63  ction] that is c
37880 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 65  reated.  The ide
37890 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a 2a  a here is that.*
378a0 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  * xEntryPoint() 
378b0 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  is the entry poi
378c0 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 61  nt for a statica
378d0 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74  lly linked SQLit
378e0 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74  e extension.** t
378f0 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 74  hat is to be aut
37900 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65  omatically loade
37910 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64  d into all new d
37920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37930 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  ons..**.** ^(Eve
37940 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 6e  n though the fun
37950 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20  ction prototype 
37960 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 72  shows that xEntr
37970 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a  yPoint() takes.*
37980 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61  * no arguments a
37990 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 2c  nd returns void,
379a0 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
379b0 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
379c0 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 75  th three.** argu
379d0 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 74  ments and expect
379e0 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 65  s and integer re
379f0 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 73  sult as if the s
37a00 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 0a  ignature of the.
37a10 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 77  ** entry point w
37a20 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  here as follows:
37a30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
37a40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73  te><pre>.** &nbs
37a50 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 6f  p;  int xEntryPo
37a60 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  int(.** &nbsp;  
37a70 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a    sqlite3 *db,.*
37a80 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
37a90 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73  t char **pzErrMs
37aa0 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  g,.** &nbsp;    
37ab0 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
37ac0 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
37ad0 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62  s *pThunk.** &nb
37ae0 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  sp;  );.** </pre
37af0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
37b00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 45  .**.** If the xE
37b10 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e  ntryPoint routin
37b20 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20  e encounters an 
37b30 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64  error, it should
37b40 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a   make *pzErrMsg.
37b50 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ** point to an a
37b60 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
37b70 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 6e   message (obtain
37b80 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37b90 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20  _mprintf()]).** 
37ba0 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 70  and return an ap
37bb0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
37bc0 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65   code].  ^SQLite
37bd0 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a 70   ensures that *p
37be0 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55  zErrMsg.** is NU
37bf0 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  LL before callin
37c00 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  g the xEntryPoin
37c10 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  t().  ^SQLite wi
37c20 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71  ll invoke.** [sq
37c30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
37c40 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 72   *pzErrMsg after
37c50 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
37c60 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79  eturns.  ^If any
37c70 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
37c80 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  ) returns an err
37c90 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  or, the [sqlite3
37ca0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
37cb0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
37cc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
37cd0 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 61  n_v2()] call tha
37ce0 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 78  t provoked the x
37cf0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 6c  EntryPoint() wil
37d00 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43  l fail..**.** ^C
37d10 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 61  alling sqlite3_a
37d20 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29  uto_extension(X)
37d30 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 70   with an entry p
37d40 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 61  oint X that is a
37d50 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65  lready.** on the
37d60 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 74   list of automat
37d70 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 73  ic extensions is
37d80 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
37d90 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69  p. ^No entry poi
37da0 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61  nt.** will be ca
37db0 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  lled more than o
37dc0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 74  nce for each dat
37dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37de0 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 2e   that is opened.
37df0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37e00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
37e10 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37e20 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
37e30 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
37e40 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
37e50 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
37e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
37e70 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
37e80 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
37e90 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
37ea0 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20 61  rface disables a
37eb0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ll automatic ext
37ec0 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 73  ensions previous
37ed0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
37ee0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37ef0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37f00 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  ]..*/.void sqlit
37f10 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
37f20 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
37f30 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
37f40 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
37f50 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
37f60 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  sm is currently 
37f70 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
37f80 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
37f90 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
37fa0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37fb0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
37fc0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
37fd0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
37fe0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
37ff0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
38000 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
38010 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
38020 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
38030 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
38040 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
38050 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
38060 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
38070 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
38080 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
38090 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
380a0 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73  ** Structures us
380b0 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61  ed by the virtua
380c0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
380d0 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  e.*/.typedef str
380e0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
380f0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74   sqlite3_vtab;.t
38100 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
38110 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
38120 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
38130 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72  nfo;.typedef str
38140 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
38150 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f  _cursor sqlite3_
38160 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70  vtab_cursor;.typ
38170 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
38180 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74  te3_module sqlit
38190 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a  e3_module;../*.*
381a0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
381b0 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74  ual Table Object
381c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
381d0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69  lite3_module {vi
381e0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
381f0 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  le}.**.** This s
38200 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69  tructure, someti
38210 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 22 76 69  mes called a "vi
38220 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
38230 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
38240 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
38250 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
38260 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
38270 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
38280 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
38290 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
382a0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
382b0 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
382c0 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
382d0 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
382e0 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
382f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
38300 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
38310 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
38320 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
38330 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
38340 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
38350 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
38360 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
38370 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
38380 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
38390 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
383a0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
383b0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
383c0 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
383d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
383e0 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
383f0 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
38400 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
38410 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
38420 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
38430 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
38440 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
38450 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
38460 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
38470 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
38480 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
38490 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
384a0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
384b0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
384c0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
384d0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
384e0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
384f0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
38500 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
38510 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
38520 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
38530 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
38540 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
38550 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
38560 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
38570 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
38580 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
38590 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
385a0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
385b0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
385c0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
385d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
385e0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
385f0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
38600 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
38610 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
38620 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
38630 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
38640 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
38650 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
38660 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
38670 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
38680 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
38690 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
386a0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
386b0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
386c0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
386d0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
386e0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
386f0 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
38700 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
38710 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
38720 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
38730 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
38740 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
38750 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
38760 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
38770 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
38780 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
38790 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
387a0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
387b0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
387c0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
387d0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
387e0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
387f0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
38800 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
38810 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
38820 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
38830 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
38840 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
38850 28 73 71 6c 69 74 65 33 5f 76 74