/ Hex Artifact Content
Login

Artifact 41ce8844965b659f7a08d425dd9b5730f6d558c3:


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: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
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 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
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 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **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 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
7de0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7df0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
7e00: 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    7.../*.** CAPI
7e10: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
7e20: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
7e30: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
7e40: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
7e50: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
7e60: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
7e70: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
7e80: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
7e90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
7ea0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
7eb0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
7ec0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
7ed0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
7ee0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
7ef0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
7f00: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
7f10: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
7f20: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
7f30: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
7f40: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
7f50: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
7f60: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7f70: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
7f80: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
7f90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7fa0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
7fb0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
7fc0: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
7fd0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
7fe0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
7ff0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
8000: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
8010: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
8020: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
8030: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
8040: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
8050: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
8060: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
8070: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
8080: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
8090: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
80a0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
80b0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
80c0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
80d0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
80e0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
80f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
8100: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
8110: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
8120: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
8130: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
8140: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
8150: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
8160: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
8170: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
8180: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
8190: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
81a0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
81b0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
81c0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
81d0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
81e0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
81f0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
8200: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
8210: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
8220: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
8230: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
8240: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
8250: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
8260: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
8270: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
8280: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
8290: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
82a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
82b0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
82c0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
82d0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
82e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
82f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
8300: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
8310: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
8320: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
8330: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
8340: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
8350: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
8360: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
8370: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
8380: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
8390: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
83a0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
83b0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
83c0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
83d0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
83e0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
83f0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
8400: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
8410: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
8420: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
8430: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
8440: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
8450: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
8460: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
8470: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
8480: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
8490: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
84a0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
84b0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
84c0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
84d0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
84e0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
84f0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
8500: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
8510: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
8520: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
8530: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
8540: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
8550: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
8560: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
8570: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
8580: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
8590: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  modules..**.** ^
85a0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
85b0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
85c0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
85d0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
85e0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
85f0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
8600: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
8610: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
8620: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
8630: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
8640: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
8650: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
8660: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8670: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
8680: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
8690: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
86a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
86b0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61  ore than.** 10 a
86c0: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
86d0: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
86e0: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
86f0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
8700: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
8710: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
8720: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
8730: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
8740: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
8750: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
8760: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
8770: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8780: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8790: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
87a0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
87b0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
87c0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
87d0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
87e0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
87f0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8800: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
8810: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8820: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8830: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
8840: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8850: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8860: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
8870: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8880: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8890: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
88a0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
88b0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
88c0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
88d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
88e0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
88f0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8900: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8910: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8920: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8930: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8940: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8950: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8960: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8970: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8980: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8990: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
89a0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
89b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
89c0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
89d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
89e0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
89f0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8a00: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8a10: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8a20: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8a30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8a40: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8a50: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8a60: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8a70: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
8a80: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8a90: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8aa0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8ab0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
8ac0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
8ad0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
8ae0: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
8af0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8b00: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
8b10: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8b20: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
8b30: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8b40: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
8b50: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8b60: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
8b70: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8b80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8b90: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
8ba0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
8bb0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
8bc0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8bd0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
8be0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8bf0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
8c00: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
8c10: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
8c20: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
8c30: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
8c40: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
8c50: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
8c60: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
8c70: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
8c80: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
8c90: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
8ca0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
8cb0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
8cc0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
8cd0: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
8ce0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
8cf0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
8d00: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
8d10: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
8d20: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
8d30: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
8d40: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
8d50: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
8d60: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
8d70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
8d80: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
8d90: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
8da0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
8db0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
8dc0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
8dd0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
8de0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
8df0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
8e00: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
8e10: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
8e20: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
8e30: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8e40: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
8e50: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
8e60: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
8e70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8e80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8e90: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
8ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8eb0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
8ec0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ed0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8ee0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
8ef0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
8f00: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
8f10: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
8f20: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
8f30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8f40: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8f50: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
8f60: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
8f70: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
8f80: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
8f90: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
8fa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
8fb0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8fc0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
8fd0: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
8fe0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
8ff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
9000: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
9010: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
9020: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
9030: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
9040: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
9050: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
9060: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
9070: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
9080: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
9090: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
90a0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
90b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
90c0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
90d0: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
90e0: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
90f0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
9100: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
9110: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
9120: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
9130: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
9140: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
9150: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
9160: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
9170: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
9180: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
9190: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
91a0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
91b0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
91c0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
91d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
91e0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
91f0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
9200: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
9210: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
9220: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
9230: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
9240: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
9250: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
9260: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
9270: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
9280: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
9290: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
92a0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
92b0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
92c0: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
92d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
92e0: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
92f0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
9300: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
9310: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
9320: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
9330: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
9340: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
9350: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
9360: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
9370: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
9380: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
9390: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
93a0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
93b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ..**.** ^The fla
93c0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
93d0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
93e0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
93f0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
9400: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
9410: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
9420: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
9430: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
9440: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9450: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9460: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
9470: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9480: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
9490: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
94a0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
94b0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
94c0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
94d0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
94e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
94f0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
9500: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
9510: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
9520: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
9530: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
9540: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9550: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9560: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9570: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9580: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9590: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
95a0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
95b0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
95c0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
95d0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
95e0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
95f0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
9600: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
9610: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
9620: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9630: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9640: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9650: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9660: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9670: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9680: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9690: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
96a0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
96b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
96c0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
96d0: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
96e0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
96f0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9700: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9710: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9720: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9730: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9740: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9750: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9760: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9770: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9780: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9790: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
97a0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
97b0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
97c0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
97d0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
97e0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
97f0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9800: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9810: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9820: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9830: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9840: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9850: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9860: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9870: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9880: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
9890: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
98a0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
98b0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
98c0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
98d0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
98e0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
98f0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9900: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
9910: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
9920: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9930: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9940: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9950: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9960: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9970: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9980: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9990: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
99a0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
99b0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
99c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
99d0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
99e0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
99f0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
9a00: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
9a10: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
9a20: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9a30: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9a40: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9a50: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9a60: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9a70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9a80: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9a90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9aa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9ab0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
9ac0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
9ad0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
9ae0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
9af0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
9b00: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
9b10: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
9b20: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9b30: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9b40: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9b50: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9b60: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9b70: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9b80: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9b90: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9ba0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
9bb0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
9bc0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
9bd0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
9be0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
9bf0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
9c00: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9c10: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9c20: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9c30: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9c40: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
9c50: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
9c60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9c70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9c80: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
9c90: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
9ca0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
9cb0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
9cc0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
9cd0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9ce0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9cf0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
9d00: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
9d10: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9d20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9d30: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
9d40: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
9d50: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
9d60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9d70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9d80: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
9d90: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
9da0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
9db0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9dc0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
9dd0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
9de0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9df0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
9e00: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
9e10: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
9e20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
9e30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9e40: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
9e50: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
9e60: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9e70: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
9e80: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
9e90: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9ea0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
9eb0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
9ec0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
9ed0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
9ee0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
9ef0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
9f00: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
9f10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
9f20: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
9f30: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
9f40: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
9f50: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
9f60: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
9f70: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
9f80: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
9f90: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
9fa0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
9fb0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
9fc0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
9fd0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
9fe0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
9ff0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
a000: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
a010: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a020: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a030: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
a040: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
a050: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
a060: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
a070: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
a080: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
a090: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
a0a0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
a0b0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
a0c0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
a0d0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
a0e0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a0f0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
a100: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
a110: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a120: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a130: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a140: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a150: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a160: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a170: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a180: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a190: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a1a0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a1b0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a1c0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a1d0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a1e0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a1f0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a200: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a210: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a220: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a230: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a240: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a250: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a260: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a270: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a280: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a290: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a2a0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a2b0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a2c0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a2d0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a2e0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a2f0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a300: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a310: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a320: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a330: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a340: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a350: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a360: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a370: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a380: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a390: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a3a0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a3b0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a3c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a3d0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a3e0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a3f0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a400: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a410: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a420: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a430: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a440: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a450: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a460: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a480: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a4a0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a4b0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
a4c0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
a4d0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
a4e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a4f0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
a500: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
a510: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
a520: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
a530: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
a540: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a550: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
a560: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
a570: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
a580: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
a590: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
a5a0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
a5b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
a5c0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
a5d0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
a5e0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
a5f0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
a600: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
a610: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a620: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a630: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a640: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
a650: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a660: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
a670: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
a680: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a690: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
a6a0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
a6b0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
a6c0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
a6d0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
a6e0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
a6f0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
a700: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
a710: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
a720: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
a730: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
a740: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
a750: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
a760: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
a770: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
a780: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
a790: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
a7a0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
a7b0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
a7c0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
a7d0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
a7e0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
a7f0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
a800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a810: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
a820: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
a830: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
a840: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a850: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
a860: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
a870: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a880: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
a890: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
a8a0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
a8b0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
a8c0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
a8d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a8e0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
a8f0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
a900: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
a910: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
a920: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
a930: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
a940: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
a950: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
a960: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
a970: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
a980: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
a990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a9a0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
a9b0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
a9c0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
a9d0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
a9e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a9f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa00: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
aa10: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
aa20: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
aa30: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
aa40: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
aa50: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
aa60: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
aa70: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
aa80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
aa90: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
aaa0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
aab0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
aac0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
aad0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
aae0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
aaf0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
ab00: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
ab10: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
ab20: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
ab30: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
ab40: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
ab50: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
ab60: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
ab70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ab80: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
ab90: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
aba0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
abb0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
abc0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
abd0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
abe0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
abf0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
ac00: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ac10: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ac20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ac30: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ac40: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
ac50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ac60: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
ac70: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
ac80: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
ac90: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
aca0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
acb0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
acc0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
acd0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
ace0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
acf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
ad00: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
ad10: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
ad20: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ad30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ad40: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
ad50: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
ad60: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
ad70: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
ad80: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
ad90: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
ada0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
adb0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
adc0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
add0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
ade0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
adf0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
ae00: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ae10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
ae20: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
ae30: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
ae40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
ae50: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
ae60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ae70: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
ae80: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
ae90: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
aea0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
aeb0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
aec0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
aed0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
aee0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
aef0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
af00: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
af10: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
af20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
af30: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
af40: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
af50: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
af60: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
af70: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
af80: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
af90: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
afa0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
afb0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
afc0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
afd0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
afe0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
aff0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
b000: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
b010: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
b020: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
b030: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b040: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
b050: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
b060: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
b070: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
b080: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
b090: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
b0a0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
b0b0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
b0c0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
b0d0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b0e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b0f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b100: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
b110: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
b120: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b130: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b140: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b150: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b160: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b170: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b180: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b190: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b1a0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b1b0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b1c0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b1d0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b1e0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b1f0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b200: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b210: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b220: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b230: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b240: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b250: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b260: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b270: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b280: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b290: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b2a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b2b0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b2c0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b2d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b2e0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b2f0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b300: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b310: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b320: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b330: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b340: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b350: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b360: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b370: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b380: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b390: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b3a0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b3b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b3c0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b3d0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b3e0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b3f0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b400: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b410: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b420: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b430: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b440: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b450: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b460: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b470: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b480: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b490: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b4a0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b4b0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
b4c0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
b4d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b4e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
b4f0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
b500: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
b510: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
b520: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
b530: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
b540: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b550: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
b560: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
b570: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
b580: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
b590: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
b5a0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
b5b0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
b5c0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
b5d0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
b5e0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
b5f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
b600: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
b610: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
b620: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
b630: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
b640: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
b650: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
b660: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
b670: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b680: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
b690: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
b6a0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
b6b0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
b6c0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
b6d0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
b6e0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
b6f0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
b700: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
b710: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b720: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
b730: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
b740: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b750: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
b760: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
b770: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
b780: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
b790: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
b7a0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
b7b0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
b7c0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
b7d0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
b7e0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
b7f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
b800: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
b810: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
b820: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
b830: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
b840: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
b850: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
b860: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
b870: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
b880: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
b890: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
b8a0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
b8b0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
b8c0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
b8d0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
b8e0: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
b8f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b900: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
b910: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
b920: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
b930: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
b940: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
b950: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
b960: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
b970: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b980: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
b990: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
b9a0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
b9b0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
b9c0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
b9d0: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
b9e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b9f0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
ba00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
ba10: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
ba20: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
ba30: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
ba40: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
ba50: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
ba60: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
ba70: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
ba80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
ba90: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
baa0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
bab0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
bac0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
bad0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
bae0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
baf0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
bb00: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
bb10: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
bb20: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
bb30: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
bb40: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
bb50: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
bb60: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
bb70: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
bb80: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
bb90: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
bba0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
bbb0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
bbc0: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
bbd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bbe0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
bbf0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
bc00: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
bc10: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
bc20: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
bc30: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
bc40: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
bc50: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
bc60: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
bc70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
bc80: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
bc90: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
bca0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
bcb0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
bcc0: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
bcd0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
bce0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
bcf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bd00: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
bd10: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
bd20: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
bd30: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
bd40: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
bd50: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
bd60: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
bd70: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
bd80: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
bd90: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
bda0: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
bdb0: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
bdc0: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
bdd0: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
bde0: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
bdf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
be00: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
be10: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
be20: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
be30: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
be40: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
be50: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
be60: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
be70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
be80: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
be90: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
bea0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
beb0: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
bec0: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
bed0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
bee0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
bef0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
bf00: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
bf10: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
bf20: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
bf30: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
bf40: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
bf50: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
bf60: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
bf70: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
bf80: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
bf90: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
bfa0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
bfb0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
bfc0: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
bfd0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
bfe0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
bff0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
c000: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
c010: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
c020: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
c030: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c040: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
c050: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c060: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
c070: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c080: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
c090: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c0a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
c0b0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
c0c0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c0d0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
c0e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
c0f0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
c100: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
c110: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c120: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c130: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c140: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c150: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c160: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c170: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c180: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c190: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c1a0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c1b0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c1c0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c1d0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c1e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c1f0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c200: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c210: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c220: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c230: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c240: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c250: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c260: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c270: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c280: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c290: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c2a0: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c2b0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c2c0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c2d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c2e0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c2f0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c300: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c310: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c320: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c330: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c340: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c350: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c360: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c370: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c380: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c390: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c3a0: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c3b0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c3c0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c3d0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c3e0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c3f0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c400: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c410: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c420: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c430: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c440: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c450: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c460: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c470: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c480: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c490: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c4a0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c4b0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c4c0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c4d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c4e0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c4f0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c500: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c510: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c520: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c530: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c540: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c550: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c560: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c570: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c580: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c590: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c5a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c5b0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
c5c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c5d0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
c5e0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
c5f0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c600: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
c610: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
c620: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
c630: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c640: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
c650: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
c660: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
c670: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
c680: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
c690: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
c6a0: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
c6b0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
c6c0: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
c6d0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
c6e0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
c6f0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
c700: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
c710: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
c720: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
c730: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
c740: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
c750: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
c760: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c770: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
c780: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
c790: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
c7a0: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
c7b0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
c7c0: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
c7d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c7e0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
c7f0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
c800: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
c810: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
c820: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
c830: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
c840: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
c850: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
c860: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
c870: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
c880: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
c890: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
c8a0: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
c8b0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
c8c0: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
c8d0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
c8e0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
c8f0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
c900: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
c910: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
c920: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
c930: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
c940: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
c950: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
c960: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
c970: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
c980: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
c990: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
c9a0: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
c9b0: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
c9c0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c9d0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
c9e0: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
c9f0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
ca00: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
ca10: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
ca20: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
ca30: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
ca40: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ca50: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ca60: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
ca70: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
ca80: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ca90: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
caa0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
cab0: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
cac0: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
cad0: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
cae0: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
caf0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
cb00: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
cb10: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
cb20: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
cb30: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
cb40: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
cb50: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
cb60: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
cb70: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
cb80: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
cb90: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
cba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
cbb0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
cbc0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
cbd0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
cbe0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cbf0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
cc00: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
cc10: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
cc20: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
cc30: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
cc40: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
cc50: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
cc60: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
cc70: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
cc80: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
cc90: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
cca0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
ccb0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
ccc0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
ccd0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
cce0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
ccf0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
cd00: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
cd10: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
cd20: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
cd30: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
cd40: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
cd50: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
cd60: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
cd70: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
cd80: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
cd90: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
cda0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
cdb0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
cdc0: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
cdd0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
cde0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
cdf0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
ce00: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
ce10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
ce20: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
ce30: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
ce40: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
ce50: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
ce60: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
ce70: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
ce80: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
ce90: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
cea0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
ceb0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
cec0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
ced0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
cee0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
cef0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
cf00: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
cf10: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
cf20: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
cf30: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
cf40: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
cf50: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
cf60: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
cf70: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
cf80: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
cf90: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
cfa0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
cfb0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
cfc0: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
cfd0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
cfe0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
cff0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
d000: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
d010: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
d020: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
d030: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
d040: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
d050: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d060: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
d070: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
d080: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
d090: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
d0a0: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
d0b0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
d0c0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
d0d0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
d0e0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
d0f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d100: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
d110: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d120: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d130: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d140: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d150: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d160: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d170: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d180: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d190: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d1a0: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d1b0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d1c0: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d1d0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d1e0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d1f0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d200: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d210: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d220: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d230: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d240: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d250: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d260: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d270: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d280: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d290: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d2a0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d2b0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d2c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d2d0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d2e0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d2f0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d300: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d310: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d320: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d330: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d340: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d350: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d360: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d370: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d380: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d390: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d3a0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d3b0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d3c0: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d3d0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d3e0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d3f0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d400: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d410: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d420: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d430: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d440: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d450: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d460: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d470: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d480: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d490: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d4a0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d4b0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
d4c0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d4d0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
d4e0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
d4f0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
d500: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d510: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
d520: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
d530: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
d540: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
d550: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
d560: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d570: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
d580: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
d590: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d5a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d5b0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
d5c0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
d5d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d5e0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
d5f0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d600: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
d610: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
d620: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d630: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
d640: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
d650: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
d660: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
d670: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
d680: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
d690: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
d6a0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
d6b0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
d6c0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d6d0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
d6e0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
d6f0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
d700: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
d710: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
d720: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d730: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
d740: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
d750: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d760: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
d770: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d780: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d790: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d7a0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d7b0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d7c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d7d0: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
d7e0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d7f0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
d800: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
d810: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
d820: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
d830: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
d840: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
d850: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
d860: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d870: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d880: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d890: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d8a0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d8b0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d8c0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d8d0: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
d8e0: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
d8f0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
d900: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
d910: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
d920: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
d930: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
d940: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
d950: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d960: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
d970: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
d980: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
d990: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d9a0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d9b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d9c0: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
d9d0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d9e0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d9f0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
da00: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
da10: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
da20: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
da30: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
da40: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
da50: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
da60: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
da70: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
da80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
da90: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
daa0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
dab0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
dac0: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
dad0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
dae0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
daf0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
db00: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
db10: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
db20: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
db30: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
db40: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
db50: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
db60: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
db70: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
db80: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
db90: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
dba0: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
dbb0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
dbc0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
dbd0: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
dbe0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
dbf0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
dc00: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
dc10: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
dc20: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
dc30: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
dc40: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
dc50: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
dc60: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
dc70: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
dc80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
dc90: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
dca0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
dcb0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
dcc0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
dcd0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
dce0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dcf0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
dd00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dd10: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
dd20: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
dd30: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
dd40: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
dd50: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
dd60: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
dd70: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
dd80: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
dd90: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
dda0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
ddb0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
ddc0: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
ddd0: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
dde0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ddf0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
de00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
de10: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
de20: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
de30: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
de40: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
de50: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
de60: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
de70: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
de80: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
de90: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
dea0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
deb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
dec0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
ded0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
dee0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
def0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
df00: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
df10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
df20: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
df30: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
df40: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
df50: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
df60: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
df70: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
df80: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
df90: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
dfa0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
dfb0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
dfc0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
dfd0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
dfe0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
dff0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
e000: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
e010: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
e020: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e030: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
e040: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e050: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
e060: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
e070: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
e080: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e090: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e0a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e0b0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
e0c0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e0d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e0e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e0f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e100: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
e110: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e120: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e130: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e140: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e150: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e160: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e170: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e180: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e190: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e1a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e1b0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e1c0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e1d0: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e1e0: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e1f0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e200: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e210: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e220: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e230: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e240: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e250: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e260: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e270: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e280: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e290: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e2a0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e2b0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e2c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e2d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e2e0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e2f0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e300: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e310: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e320: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e330: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e340: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e350: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e360: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e370: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e380: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e390: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e3a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e3b0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e3c0: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e3d0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e3e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e3f0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e400: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e410: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e420: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e430: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e440: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e450: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e460: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e470: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e480: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e490: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e4a0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e4b0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
e4c0: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
e4f0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
e500: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e510: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e520: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
e530: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
e540: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
e550: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
e560: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
e570: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e580: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
e590: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
e5a0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
e5b0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e5c0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
e5d0: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
e5e0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
e5f0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
e600: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
e610: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e620: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
e630: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
e640: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
e650: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
e660: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
e670: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
e680: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
e690: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
e6a0: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
e6b0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
e6c0: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
e6d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e6e0: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
e6f0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
e700: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
e710: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
e720: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
e730: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
e740: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
e750: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e760: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
e770: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
e780: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
e790: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
e7a0: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
e7b0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
e7c0: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
e7d0: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
e7e0: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
e7f0: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
e800: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
e810: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
e820: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
e830: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
e840: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
e850: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
e860: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e870: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
e880: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
e890: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
e8a0: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
e8b0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
e8c0: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
e8d0: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
e8e0: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
e8f0: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
e900: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
e910: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
e920: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
e930: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
e940: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
e950: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
e960: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
e970: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
e980: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
e990: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
e9a0: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
e9b0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
e9c0: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
e9d0: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
e9e0: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
e9f0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
ea00: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
ea10: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
ea20: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ea30: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
ea40: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
ea50: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
ea60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ea70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ea80: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
ea90: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
eaa0: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
eab0: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
eac0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
ead0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
eae0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
eaf0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
eb00: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
eb10: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
eb20: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
eb30: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
eb40: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
eb50: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
eb60: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
eb70: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
eb80: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
eb90: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
eba0: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
ebb0: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
ebc0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
ebd0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
ebe0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
ebf0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
ec00: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
ec10: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
ec20: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
ec30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
ec40: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
ec50: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
ec60: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
ec70: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
ec80: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
ec90: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
eca0: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
ecb0: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
ecc0: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
ecd0: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
ece0: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
ecf0: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
ed00: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
ed10: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
ed20: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
ed30: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
ed40: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
ed50: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
ed60: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
ed70: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
ed80: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
ed90: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
eda0: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
edb0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
edc0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
edd0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
ede0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
edf0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
ee00: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
ee10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
ee20: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
ee30: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
ee40: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
ee50: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
ee60: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
ee70: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
ee80: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
ee90: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
eea0: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
eeb0: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
eec0: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
eed0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
eee0: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
eef0: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
ef00: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
ef10: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
ef20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
ef30: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
ef40: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
ef50: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
ef60: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
ef70: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
ef80: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
ef90: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
efa0: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
efb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
efc0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
efd0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
efe0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
eff0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
f000: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
f010: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
f020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f030: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
f040: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
f050: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f060: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
f070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f080: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
f090: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f0a0: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
f0b0: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
f0c0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
f0d0: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
f0e0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
f0f0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
f100: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
f110: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
f120: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
f130: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f140: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
f150: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
f160: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
f170: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
f180: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f190: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
f1a0: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
f1b0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
f1c0: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
f1d0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
f1e0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f1f0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
f200: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
f210: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
f220: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
f230: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
f240: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
f250: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
f260: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
f270: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
f280: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
f290: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
f2a0: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
f2b0: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
f2c0: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
f2d0: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
f2e0: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
f2f0: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
f300: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f310: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
f320: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f330: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
f340: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f350: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f360: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f370: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
f380: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f390: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f3a0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f3b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f3c0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f3d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f3e0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f3f0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
f400: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
f410: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
f420: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
f430: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
f440: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
f450: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
f460: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f470: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
f480: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
f490: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
f4a0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f4b0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
f4c0: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
f4d0: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
f4e0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f4f0: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
f500: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f510: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
f520: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f530: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
f540: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
f550: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
f560: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
f570: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
f580: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
f590: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
f5a0: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
f5b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f5c0: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
f5d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
f5e0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
f5f0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
f600: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f610: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
f620: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f630: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
f640: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f650: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f660: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f670: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f680: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
f690: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
f6a0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f6b0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
f6c0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
f6d0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
f6e0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
f6f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
f700: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
f710: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
f720: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
f730: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
f740: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
f750: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
f760: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
f770: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
f780: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
f790: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
f7a0: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
f7b0: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
f7c0: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
f7d0: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
f7e0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
f7f0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
f800: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
f810: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
f820: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f830: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
f840: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
f850: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
f860: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
f870: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
f880: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
f890: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
f8a0: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
f8b0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
f8c0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f8d0: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
f8e0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
f8f0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f900: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f910: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
f920: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f930: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
f940: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
f950: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
f960: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
f970: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
f980: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
f990: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
f9a0: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
f9b0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
f9c0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f9d0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
f9e0: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
f9f0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
fa00: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
fa10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
fa20: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
fa30: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
fa40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
fa50: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
fa60: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
fa70: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
fa80: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
fa90: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
faa0: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
fab0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
fac0: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
fad0: 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
fae0: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
faf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fb00: 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
fb10: 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
fb20: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fb30: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
fb40: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
fb50: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
fb60: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
fb70: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
fb80: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
fb90: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
fba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
fbb0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
fbc0: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
fbd0: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
fbe0: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
fbf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
fc00: 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
fc10: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
fc20: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
fc30: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
fc40: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
fc50: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
fc60: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
fc70: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
fc80: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
fc90: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fca0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
fcb0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
fcc0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
fcd0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
fce0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
fcf0: 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
fd00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
fd10: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
fd20: 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
fd30: 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
fd40: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fd50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
fd60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
fd70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fd80: 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
fd90: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
fda0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
fdb0: 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
fdc0: 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
fdd0: 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
fde0: 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
fdf0: 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
fe00: 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
fe10: 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
fe20: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
fe30: 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
fe40: 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
fe50: 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
fe60: 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
fe70: 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
fe80: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
fe90: 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
fea0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
feb0: 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
fec0: 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
fed0: 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
fee0: 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
fef0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ff00: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
ff10: 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
ff20: 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
ff30: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
ff40: 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
ff50: 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
ff60: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
ff70: 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
ff80: 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
ff90: 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
ffa0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
ffb0: 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
ffc0: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
ffd0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
ffe0: 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
fff0: 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
10000 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
10010 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
10020 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
10030 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
10040 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10050 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
10060 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
10070 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
10080 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
10090 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
100a0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
100b0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
100c0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
100d0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
100e0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
100f0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10100 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
10110 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
10120 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
10130 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
10140 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
10150 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
10160 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
10170 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10180 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
10190 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
101a0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
101b0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
101c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
101d0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
101e0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
101f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10200 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
10210 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
10220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10230 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10240 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
10250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10260 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10270 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
10280 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10290 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
102a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
102b0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
102c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
102d0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
102e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
102f0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
10300 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10310 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10320 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10330 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
10340 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
10350 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
10360 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10370 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
10380 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
10390 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
103a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
103b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
103c0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
103d0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
103e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
103f0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
10400 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
10410 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10420 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10430 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
10440 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
10450 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10460 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
10470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
10480 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
10490 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
104a0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
104b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
104c0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
104d0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
104e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
104f0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
10500 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
10510 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10520 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10530 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
10540 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
10550 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
10560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10570 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
10580 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
10590 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
105a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
105b0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
105c0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
105d0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
105e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
105f0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
10600 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
10610 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
10620 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
10630 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
10640 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10650 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10660 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10670 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10680 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10690 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
106a0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
106b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
106c0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
106d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
106e0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
106f0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10700 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10710 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10720 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10730 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
10740 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10750 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10760 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
10770 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10780 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10790 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
107a0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
107b0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
107c0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
107d0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
107e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
107f0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10800 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
10810 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10820 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10830 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
10840 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
10850 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
10860 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10870 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
10880 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10890 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
108a0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
108b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
108c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
108d0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
108e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
108f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10900 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
10910 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
10920 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
10930 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
10940 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
10950 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
10960 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
10970 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10980 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
10990 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
109a0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
109b0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
109c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
109d0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
109e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
109f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
10a00 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10a10 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10a20 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10a30 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
10a40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
10a50 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
10a60 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
10a70 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
10a80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10a90 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
10aa0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
10ab0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
10ac0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
10ad0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
10ae0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
10af0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
10b00 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
10b10 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
10b20 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10b30 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
10b40 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10b50 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
10b60 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
10b70 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
10b80 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
10b90 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
10ba0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
10bb0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
10bc0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
10bd0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
10be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10bf0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
10c00 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
10c10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
10c20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
10c30 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
10c40 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
10c50 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
10c60 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
10c70 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
10c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
10c90 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
10ca0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10cb0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
10cc0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
10cd0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
10ce0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
10cf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
10d00 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
10d10 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
10d20 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
10d30 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
10d40 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
10d50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
10d60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
10d70 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
10d80 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
10d90 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
10da0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
10db0 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
10dc0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
10dd0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
10de0 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
10df0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
10e00 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10e10 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
10e20 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
10e30 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
10e40 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
10e50 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
10e60 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
10e70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
10e80 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
10e90 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10ea0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
10eb0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
10ec0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
10ed0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
10ee0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
10ef0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
10f00 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
10f10 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
10f20 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
10f30 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
10f40 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
10f50 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
10f60 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
10f70 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
10f80 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
10f90 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
10fa0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
10fb0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
10fc0 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
10fd0 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
10fe0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
10ff0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
11000 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
11010 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
11020 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
11030 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
11040 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
11050 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
11060 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
11070 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
11080 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
11090 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
110a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
110b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
110c0 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
110d0 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
110e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
110f0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
11100 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
11110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
11120 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
11130 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
11140 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
11150 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
11160 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
11170 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
11180 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
11190 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
111a0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
111b0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
111c0 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
111d0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
111e0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
111f0 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
11200 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
11210 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
11220 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
11230 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
11240 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
11250 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
11260 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
11270 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
11280 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
11290 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
112a0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
112b0 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
112c0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
112d0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
112e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
112f0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
11300 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
11310 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
11320 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
11330 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11340 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11350 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
11360 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
11370 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
11380 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
11390 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
113a0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
113b0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
113c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
113d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
113e0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
113f0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
11400 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
11410 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
11420 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
11430 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
11440 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11450 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
11460 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
11470 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
11480 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
11490 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
114a0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
114b0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
114c0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
114d0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
114e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
114f0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
11500 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
11510 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
11520 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
11530 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
11540 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11550 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
11560 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
11570 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
11580 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
11590 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
115a0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
115b0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
115c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
115d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
115e0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
115f0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
11600 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
11610 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
11620 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
11630 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
11640 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11650 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
11660 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
11670 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
11680 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
11690 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
116a0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
116b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
116c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
116d0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
116e0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
116f0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11700 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11710 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11720 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11730 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11740 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11750 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11760 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11770 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
11780 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
11790 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
117a0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
117b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
117c0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
117d0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
117e0 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
117f0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11800 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11810 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11820 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11830 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11850 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11860 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11870 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11880 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11890 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
118a0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
118b0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
118c0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
118d0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
118e0 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
118f0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11900 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11910 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11920 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11930 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11940 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11950 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11960 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11970 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11980 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11990 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
119a0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
119b0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
119c0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
119d0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
119e0 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
119f0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11a00 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11a10 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11a20 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11a30 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11a40 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11a50 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11a60 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11a70 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11a80 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11a90 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11aa0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11ab0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
11ac0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
11ad0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
11ae0 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
11af0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11b00 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
11b10 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
11b20 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
11b30 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
11b40 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
11b50 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
11b60 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
11b70 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
11b80 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
11b90 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
11ba0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
11bb0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
11bc0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
11bd0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
11be0 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
11bf0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
11c00 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
11c10 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
11c20 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
11c30 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
11c40 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
11c50 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
11c60 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
11c70 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
11c80 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
11c90 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
11ca0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
11cb0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
11cc0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
11cd0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
11ce0 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
11cf0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
11d00 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
11d10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
11d20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
11d30 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
11d40 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
11d50 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
11d60 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
11d70 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
11d80 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
11d90 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
11da0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
11db0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
11dc0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
11dd0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
11de0 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
11df0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
11e00 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
11e10 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
11e20 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
11e30 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
11e40 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
11e50 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
11e60 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
11e70 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
11e80 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11e90 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11ea0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
11eb0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
11ec0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
11ed0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
11ee0 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
11ef0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
11f00 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
11f10 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
11f20 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
11f30 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
11f40 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
11f50 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
11f60 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11f70 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
11f80 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
11f90 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
11fa0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
11fb0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
11fc0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
11fd0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
11fe0 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
11ff0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
12000 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
12010 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
12020 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
12030 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
12040 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
12050 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12060 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12070 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12080 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
12090 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
120a0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
120b0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
120c0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
120d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
120e0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
120f0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
12100 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12110 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12120 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
12130 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
12140 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
12150 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
12160 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
12180 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
12190 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
121a0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
121b0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
121c0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
121d0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
121e0 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
121f0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
12200 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
12210 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12220 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
12230 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
12240 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
12250 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
12260 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
12270 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
12280 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
12290 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
122a0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
122b0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
122c0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
122d0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
122e0 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
122f0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
12300 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
12310 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
12320 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
12330 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
12340 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12350 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
12360 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
12370 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
12380 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
12390 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
123a0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
123b0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
123c0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
123d0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
123e0 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
123f0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
12400 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
12410 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
12420 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
12430 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12440 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12450 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
12460 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
12470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
12480 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
12490 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
124a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
124b0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
124c0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
124d0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
124e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
124f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
12500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
12510 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
12520 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
12530 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
12540 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12550 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
12560 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12570 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12580 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12590 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
125a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
125b0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
125c0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
125d0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
125e0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
125f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
12600 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12610 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12620 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12630 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
12640 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12650 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
12660 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
12670 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
12680 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
12690 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
126a0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
126b0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
126c0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
126d0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
126e0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
126f0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12700 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12710 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12720 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12730 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12740 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12750 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
12760 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
12770 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
12780 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
12790 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
127a0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
127b0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
127c0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
127d0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
127e0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
127f0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12800 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12810 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12820 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12830 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12840 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12860 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12870 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12880 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12890 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
128a0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
128b0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
128c0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
128d0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
128e0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
128f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12900 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12910 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12920 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12930 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12940 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12950 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12960 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12970 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12980 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12990 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
129a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
129b0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
129c0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
129d0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
129e0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
129f0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12a00 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12a10 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12a20 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12a30 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12a40 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12a50 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12a60 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12a70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12a80 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12a90 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12aa0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12ab0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
12ac0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
12ad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12ae0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
12af0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
12b00 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
12b10 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12b20 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12b30 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
12b40 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
12b50 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12b60 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
12b70 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
12b80 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
12b90 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
12ba0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
12bb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12bc0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
12bd0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12be0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12bf0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
12c00 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
12c10 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12c20 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
12c30 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
12c40 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
12c50 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
12c60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
12c70 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
12c80 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
12c90 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
12ca0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
12cb0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
12cc0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
12cd0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
12ce0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
12cf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
12d00 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
12d10 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
12d20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
12d30 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
12d40 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
12d50 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
12d60 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
12d70 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
12d80 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
12d90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
12da0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
12db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12dc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
12dd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
12de0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
12df0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12e00 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
12e10 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
12e20 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
12e30 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
12e40 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
12e50 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
12e60 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
12e70 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
12e80 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
12e90 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
12ea0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
12eb0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
12ec0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
12ed0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
12ee0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
12ef0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
12f00 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
12f10 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
12f20 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
12f30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
12f40 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
12f50 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
12f60 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
12f70 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
12f80 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
12f90 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
12fa0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12fb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
12fc0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
12fd0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
12fe0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
12ff0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
13000 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
13010 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
13020 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
13030 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
13040 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13050 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
13060 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
13070 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
13080 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
13090 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
130a0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
130b0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
130c0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
130d0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
130e0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
130f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
13100 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
13110 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
13120 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
13130 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
13140 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13150 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
13160 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
13170 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
13180 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
13190 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
131a0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
131b0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
131c0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
131d0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
131e0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
131f0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
13200 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
13210 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13220 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
13230 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
13240 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13250 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
13260 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
13270 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
13280 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
13290 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
132a0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
132b0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
132c0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
132d0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
132e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
132f0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
13300 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
13310 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13320 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
13330 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
13340 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13350 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
13360 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
13370 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
13380 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
13390 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
133a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
133b0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
133c0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
133d0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
133e0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
133f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
13400 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
13410 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
13420 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
13430 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
13440 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
13460 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
13470 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
13480 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
13490 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
134a0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
134b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
134c0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
134d0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
134e0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
134f0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
13500 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
13510 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
13520 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
13530 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
13540 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13550 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
13560 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
13570 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13580 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
13590 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
135a0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
135b0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
135c0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
135d0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
135e0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
135f0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
13600 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
13610 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
13620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
13630 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13640 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13650 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
13660 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
13670 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
13680 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
13690 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
136a0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
136b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
136c0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
136d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
136e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
136f0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13700 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13710 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13720 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13730 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13740 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13750 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
13760 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
13770 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
13780 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
13790 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
137a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
137b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
137c0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
137d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
137e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
137f0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13800 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13810 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13830 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13840 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13860 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13870 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13880 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13890 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
138a0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
138b0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
138c0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
138d0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
138e0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
138f0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13900 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13910 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13920 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13930 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13940 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13950 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13960 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13970 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13980 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13990 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
139a0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
139b0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
139c0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
139d0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
139e0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
139f0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13a00 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13a10 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13a20 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13a30 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13a40 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13a50 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13a60 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13a70 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13a80 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13a90 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13aa0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13ab0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13ac0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
13ad0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
13ae0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
13af0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
13b00 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
13b10 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13b20 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13b30 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13b40 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13b50 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
13b60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
13b70 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
13b80 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
13b90 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
13ba0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
13bb0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
13bc0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
13bd0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
13be0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
13bf0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
13c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
13c10 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
13c20 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
13c30 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
13c40 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
13c50 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
13c60 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
13c70 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
13c80 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
13c90 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
13ca0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
13cb0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
13cc0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
13cd0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
13ce0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
13cf0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
13d00 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
13d10 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
13d20 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
13d30 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
13d40 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
13d50 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
13d60 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
13d70 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
13d80 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
13d90 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
13da0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
13db0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
13dc0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
13dd0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
13de0 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
13df0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
13e00 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
13e10 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
13e20 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
13e30 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
13e40 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
13e50 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
13e60 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
13e70 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
13e80 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
13e90 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13ea0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
13eb0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
13ec0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
13ed0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
13ee0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
13ef0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
13f00 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
13f10 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
13f20 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13f30 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
13f40 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
13f50 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
13f60 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
13f70 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
13f80 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
13f90 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
13fa0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
13fb0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
13fc0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
13fd0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13fe0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
13ff0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
14000 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
14010 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
14020 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
14030 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
14040 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14050 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
14060 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
14070 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
14080 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
14090 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
140a0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
140b0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
140c0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
140d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
140e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
140f0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14100 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
14110 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
14120 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
14130 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
14140 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
14150 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
14160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14170 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
14180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
14190 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
141a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
141b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
141c0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
141d0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
141e0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
141f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
14200 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
14210 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
14220 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
14230 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14240 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
14250 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
14260 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
14270 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
14280 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
14290 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
142a0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
142b0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
142c0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
142d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
142e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
142f0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
14300 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
14310 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
14320 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14330 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
14340 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14350 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
14360 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
14370 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
14380 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
14390 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
143a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
143b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
143c0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
143d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
143e0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
143f0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
14400 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
14410 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
14420 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
14430 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
14440 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14460 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
14470 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
14480 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
14490 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
144a0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
144b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
144c0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
144d0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
144e0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
144f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
14500 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
14510 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14520 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14530 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14540 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14550 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14560 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14570 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
14580 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
14590 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
145a0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
145b0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
145c0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
145d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
145e0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
145f0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
14600 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
14610 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
14620 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
14630 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
14640 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
14650 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
14660 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
14670 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
14680 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
14690 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
146a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
146b0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
146c0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
146d0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
146e0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
146f0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
14700 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
14710 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
14720 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
14730 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
14740 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
14750 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
14760 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
14770 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
14780 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
14790 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
147a0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
147b0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
147c0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
147d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
147e0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
147f0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
14800 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
14810 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
14820 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
14830 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
14840 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
14850 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
14860 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
14870 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
14880 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
14890 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
148a0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
148b0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
148c0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
148d0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
148e0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
148f0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
14900 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14910 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
14920 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
14930 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14940 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
14950 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14960 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
14970 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
14980 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14990 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
149a0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
149b0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
149c0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
149d0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
149e0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
149f0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
14a00 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
14a10 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14a20 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
14a30 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14a40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
14a50 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14a60 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14a70 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14a80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14a90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14aa0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14ab0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
14ac0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14ad0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
14ae0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
14af0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
14b00 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
14b10 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
14b20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
14b30 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14b40 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
14b50 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
14b60 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
14b70 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
14b80 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
14b90 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
14ba0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
14bb0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
14bc0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
14bd0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
14be0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
14bf0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
14c00 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
14c10 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14c20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14c30 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
14c40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14c50 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
14c60 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14c70 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
14c80 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
14c90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
14ca0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
14cb0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14cc0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
14cd0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14ce0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
14cf0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14d00 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
14d10 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
14d20 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
14d30 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
14d40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
14d50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14d60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14d70 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14d80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14d90 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14da0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14db0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14dc0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14dd0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14de0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
14df0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
14e00 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
14e10 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
14e20 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
14e30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
14e40 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
14e50 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
14e60 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
14e70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
14e80 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
14e90 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
14ea0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
14eb0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
14ec0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
14ed0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
14ee0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
14ef0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
14f00 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
14f10 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
14f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
14f30 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
14f40 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14f50 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14f60 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14f70 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14f80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14f90 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14fb0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
14fc0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
14fd0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
14fe0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
14ff0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15000 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
15010 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
15020 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
15030 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
15040 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
15050 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
15060 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
15070 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
15080 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
15090 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
150a0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
150b0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
150c0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
150d0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
150e0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
150f0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
15100 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
15110 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
15120 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
15130 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
15140 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
15150 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
15160 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
15170 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
15180 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
15190 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
151a0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
151b0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
151c0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
151d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
151e0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
151f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
15200 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
15210 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
15220 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
15230 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
15240 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15250 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
15260 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
15270 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
15280 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
15290 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
152a0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
152b0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
152c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
152d0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
152e0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
152f0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
15300 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
15310 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
15320 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
15330 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
15340 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15350 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
15360 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
15370 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
15380 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
15390 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
153a0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
153b0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
153c0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
153d0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
153e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
153f0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
15400 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
15410 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
15420 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
15430 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
15440 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
15450 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
15460 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
15470 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
15480 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
15490 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
154a0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
154b0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
154c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
154d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
154e0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
154f0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
15500 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
15510 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
15520 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
15530 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
15540 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
15550 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
15560 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
15570 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
15580 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
15590 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
155a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
155b0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
155c0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
155d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
155e0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
155f0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
15600 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
15610 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
15620 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
15630 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
15640 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
15650 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
15660 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
15670 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
15680 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
15690 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
156a0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
156b0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
156c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
156d0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
156e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
156f0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
15700 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
15710 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
15720 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
15730 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
15740 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
15750 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
15760 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
15770 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15780 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
15790 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
157a0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
157b0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
157c0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
157d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
157e0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
157f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
15800 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
15810 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
15820 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
15830 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
15840 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
15850 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
15860 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
15870 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
15880 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
15890 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
158a0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
158b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
158c0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
158d0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
158e0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
158f0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
15900 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
15910 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
15920 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
15930 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
15940 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
15950 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
15960 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
15970 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
15980 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
15990 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
159a0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
159b0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
159c0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
159d0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
159e0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
159f0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
15a00 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
15a10 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
15a20 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
15a30 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
15a40 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
15a50 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
15a60 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
15a70 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
15a80 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
15a90 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
15aa0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
15ab0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
15ac0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
15ad0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
15ae0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
15af0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
15b00 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
15b10 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
15b20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15b30 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15b40 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15b50 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15b60 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15b70 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15b80 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15b90 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15ba0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
15bb0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
15bc0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
15bd0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
15be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
15bf0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
15c00 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
15c10 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
15c20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15c30 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
15c40 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
15c50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
15c60 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
15c70 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15c80 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
15c90 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
15ca0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
15cb0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
15cc0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
15cd0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
15ce0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
15cf0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
15d00 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
15d10 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15d20 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
15d30 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
15d40 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
15d50 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
15d60 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
15d70 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
15d80 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
15d90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
15da0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
15db0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
15dc0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
15dd0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
15de0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
15df0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15e00 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
15e10 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
15e20 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
15e30 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
15e40 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
15e50 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
15e60 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
15e70 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15e80 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
15e90 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
15ea0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
15eb0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
15ec0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15ed0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
15ee0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
15ef0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
15f00 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
15f10 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
15f20 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
15f30 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
15f40 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
15f50 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
15f60 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
15f70 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
15f80 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
15f90 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
15fa0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
15fb0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
15fc0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
15fd0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
15fe0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
15ff0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
16000 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
16010 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16020 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
16030 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
16040 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
16050 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
16060 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
16070 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
16080 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16090 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
160a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
160b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
160c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
160d0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
160e0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
160f0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
16100 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
16110 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
16120 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16130 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
16140 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
16150 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
16160 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
16170 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
16180 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
16190 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
161a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
161b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
161c0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
161d0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
161e0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
161f0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
16200 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
16210 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
16220 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
16230 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
16240 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16250 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
16260 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
16270 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
16280 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
16290 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
162a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
162b0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
162c0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
162d0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
162e0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
162f0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
16300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16310 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
16320 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
16330 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
16340 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
16350 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
16360 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
16370 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
16380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
16390 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
163a0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
163b0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
163c0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
163d0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
163e0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
163f0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
16400 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
16410 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
16420 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
16430 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
16440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16450 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
16460 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
16470 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
16480 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
16490 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
164a0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
164b0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
164c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
164d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
164e0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
164f0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
16500 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
16510 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
16520 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
16530 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
16540 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
16550 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
16560 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
16570 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
16580 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
16590 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
165a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
165b0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
165c0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
165d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
165e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
165f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
16600 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
16610 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
16620 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
16630 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
16640 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
16650 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
16660 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
16670 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
16680 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
16690 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
166a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
166b0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
166c0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
166d0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
166e0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
166f0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
16700 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
16710 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
16720 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
16730 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
16740 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
16750 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
16760 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
16770 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
16780 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
16790 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
167a0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
167b0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
167c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
167d0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
167e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
167f0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
16800 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
16810 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
16820 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16830 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
16840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
16860 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
16870 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
16880 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
16890 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
168a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
168b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
168c0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
168d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
168e0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
168f0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
16900 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
16910 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16920 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16930 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
16940 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
16950 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
16960 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
16970 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
16980 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
16990 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
169a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
169b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
169c0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
169d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
169e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
169f0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
16a00 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
16a10 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
16a20 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
16a30 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
16a40 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
16a50 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
16a60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
16a70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
16a80 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
16a90 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
16aa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16ab0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
16ac0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
16ad0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
16ae0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
16af0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
16b00 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
16b10 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
16b20 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
16b30 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
16b40 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
16b50 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
16b60 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
16b70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
16b80 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
16b90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16ba0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16bb0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
16bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
16bd0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
16be0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
16bf0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
16c00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
16c10 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
16c20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
16c30 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
16c40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
16c50 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
16c60 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
16c70 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
16c80 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
16c90 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
16ca0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
16cb0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
16cc0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
16cd0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
16ce0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
16cf0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
16d00 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
16d10 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
16d20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
16d30 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
16d40 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
16d50 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
16d60 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
16d70 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
16d80 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
16d90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
16da0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
16db0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
16dc0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
16dd0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
16de0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
16df0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
16e00 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
16e10 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
16e20 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
16e30 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
16e40 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
16e50 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
16e60 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
16e70 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
16e80 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
16e90 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
16ea0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
16eb0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
16ec0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
16ed0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
16ee0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
16ef0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
16f00 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
16f10 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
16f20 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
16f30 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
16f40 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
16f50 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
16f60 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
16f70 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
16f80 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
16f90 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
16fa0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
16fb0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
16fc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16fd0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
16fe0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
16ff0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
17000 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
17010 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
17020 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
17030 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
17040 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17050 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
17060 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
17070 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
17080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
17090 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
170a0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
170b0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
170c0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
170d0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
170e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
170f0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
17100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17110 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
17120 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
17130 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
17140 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
17150 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
17160 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
17170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
17180 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
17190 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
171a0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
171b0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
171c0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
171d0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
171e0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
171f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
17200 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17210 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
17220 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
17230 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
17240 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
17250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17260 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
17270 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
17280 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
17290 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
172a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
172b0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
172c0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
172d0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
172e0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
172f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
17300 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
17310 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
17320 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
17330 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
17340 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
17350 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
17360 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
17370 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
17380 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
17390 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
173a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
173b0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
173c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
173d0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
173e0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
173f0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
17400 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
17410 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
17420 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
17430 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
17440 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
17450 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
17460 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
17470 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
17480 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
17490 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
174a0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
174b0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
174c0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
174d0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
174e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
174f0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
17500 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
17510 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
17520 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
17530 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
17540 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
17550 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
17560 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
17570 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
17580 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
17590 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
175a0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
175b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
175c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
175d0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
175e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
175f0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
17600 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
17610 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
17620 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
17630 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
17640 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
17650 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
17660 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
17670 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
17680 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
17690 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
176a0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
176b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
176c0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
176d0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
176e0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
176f0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
17700 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
17710 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
17720 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
17730 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
17740 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
17750 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
17760 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
17770 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
17780 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
17790 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
177a0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
177b0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
177c0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
177d0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
177e0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
177f0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
17800 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
17810 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
17820 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
17830 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
17840 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
17850 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
17860 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
17870 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
17880 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
17890 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
178a0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
178b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
178c0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
178d0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
178e0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
178f0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
17900 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
17910 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
17920 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
17930 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17940 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
17950 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
17960 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
17970 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
17980 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
17990 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
179a0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
179b0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
179c0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
179d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
179e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
179f0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
17a00 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
17a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
17a20 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
17a30 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
17a40 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
17a50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17a60 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
17a70 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
17a80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
17a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17aa0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
17ab0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
17ac0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
17ad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
17ae0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
17af0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
17b00 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
17b10 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
17b20 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
17b30 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
17b40 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
17b50 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
17b60 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
17b70 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
17b80 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
17b90 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
17ba0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
17bb0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
17bc0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
17bd0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
17be0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
17bf0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
17c00 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
17c10 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
17c20 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
17c30 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
17c40 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
17c50 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
17c60 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
17c70 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
17c80 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
17c90 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
17ca0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
17cb0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
17cc0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
17cd0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17ce0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17cf0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
17d00 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
17d10 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
17d20 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
17d30 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
17d40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
17d50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
17d60 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
17d70 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
17d80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
17d90 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
17da0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
17db0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
17dc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17dd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
17de0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
17df0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
17e00 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
17e10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17e20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
17e30 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
17e40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17e50 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
17e60 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
17e70 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
17e80 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
17e90 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
17ea0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
17eb0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
17ec0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
17ed0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
17ee0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
17ef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17f00 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
17f10 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
17f20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
17f30 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17f40 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
17f50 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
17f60 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
17f70 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
17f80 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
17f90 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
17fa0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
17fb0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
17fc0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
17fd0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
17fe0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
17ff0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
18000 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
18010 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
18020 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
18030 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
18040 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
18050 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
18060 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
18070 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
18080 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
18090 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
180a0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
180b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
180c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
180d0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
180e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
180f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
18100 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
18110 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
18120 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
18130 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
18140 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
18150 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
18160 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
18170 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
18180 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
18190 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
181a0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
181b0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
181c0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
181d0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
181e0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
181f0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
18200 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
18210 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
18220 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
18230 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
18240 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
18250 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
18260 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
18270 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
18280 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
18290 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
182a0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
182b0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
182c0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
182d0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
182e0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
182f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
18300 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
18310 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
18320 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
18330 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
18340 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
18350 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
18360 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
18370 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
18380 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
18390 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
183a0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
183b0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
183c0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
183d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
183e0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
183f0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
18400 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
18410 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
18420 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
18430 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
18440 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
18450 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
18460 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
18470 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
18480 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
18490 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
184a0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
184b0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
184c0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
184d0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
184e0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
184f0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
18500 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
18510 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
18520 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
18530 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
18540 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
18550 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
18560 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
18570 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
18580 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
18590 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
185a0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
185b0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
185c0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
185d0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
185e0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
185f0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
18600 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
18610 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
18620 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
18630 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
18640 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
18650 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
18660 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
18670 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
18680 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
18690 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
186a0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
186b0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
186c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
186d0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
186e0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
186f0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
18700 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
18710 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
18720 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
18730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
18740 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
18750 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
18760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18770 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
18780 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
18790 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
187a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
187b0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
187c0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
187d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
187e0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
187f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
18800 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
18810 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
18820 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
18830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
18840 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
18850 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
18860 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
18870 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
18880 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18890 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
188a0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
188b0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
188c0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
188d0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
188e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
188f0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
18900 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
18910 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
18920 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
18930 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
18940 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
18950 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
18960 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
18970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
18980 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
18990 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
189a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
189b0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
189c0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
189d0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
189e0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
189f0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
18a00 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
18a10 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
18a20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
18a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18a40 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
18a50 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
18a60 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
18a70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
18a80 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
18a90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
18aa0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
18ab0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
18ac0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
18ad0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
18ae0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
18af0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
18b00 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
18b10 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
18b20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18b30 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18b40 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
18b50 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
18b60 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
18b70 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
18b80 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
18b90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18ba0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18bb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
18bc0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
18bd0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
18be0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
18bf0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
18c00 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
18c10 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
18c20 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
18c30 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
18c40 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
18c50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
18c60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18c70 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
18c80 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
18c90 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
18ca0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
18cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
18cc0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
18cd0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18ce0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
18cf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d00 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
18d10 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
18d20 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
18d30 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
18d40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18d50 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
18d60 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
18d70 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
18d80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
18d90 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
18da0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
18db0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
18dc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
18dd0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
18de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
18df0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
18e00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18e10 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
18e20 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
18e30 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
18e40 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
18e50 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
18e60 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
18e70 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
18e80 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
18e90 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
18ea0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
18eb0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
18ec0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
18ed0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
18ee0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
18ef0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
18f00 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
18f10 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
18f20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
18f30 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
18f40 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
18f50 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
18f60 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
18f70 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
18f80 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
18f90 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
18fa0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
18fb0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
18fc0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
18fd0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
18fe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
18ff0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
19000 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
19010 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
19020 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
19030 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
19040 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
19050 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
19060 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
19070 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
19080 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
19090 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
190a0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
190b0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
190c0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
190d0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
190e0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
190f0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
19100 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
19110 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19130 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
19140 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
19150 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
19160 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
19170 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
19180 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19190 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
191a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
191b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
191c0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
191d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
191e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
191f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19200 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
19210 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
19220 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19230 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19240 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19250 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
19260 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
19270 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19280 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19290 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
192a0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
192b0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
192c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
192d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
192e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
192f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
19300 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
19310 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
19320 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19340 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
19350 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
19360 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19370 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19390 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
193a0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
193b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
193c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
193d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
193e0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
193f0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
19400 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19410 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19430 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
19440 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
19450 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19460 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19480 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
19490 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
194a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
194b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
194c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
194d0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
194e0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
194f0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19500 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19510 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19520 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
19530 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
19540 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19550 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19560 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19570 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
19580 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
19590 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
195a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
195b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
195c0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
195d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
195e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
195f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19600 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
19610 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
19620 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19630 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19640 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19650 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
19660 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
19670 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19680 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19690 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
196a0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
196b0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
196c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
196d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
196e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
196f0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
19700 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
19710 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
19720 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
19730 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
19740 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
19750 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
19760 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19770 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
19780 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19790 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
197a0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
197b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
197c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
197d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
197e0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
197f0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
19800 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
19810 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19830 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
19840 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
19850 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
19860 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
19870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19880 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
19890 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
198a0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
198b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
198c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
198d0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
198e0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
198f0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
19900 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
19920 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
19930 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
19940 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
19950 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
19970 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
19980 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
19990 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
199a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
199b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
199c0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
199d0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
199e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
199f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19a00 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19a10 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
19a20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
19a30 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
19a40 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19a50 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
19a60 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
19a70 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
19a80 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
19a90 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19aa0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
19ab0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
19ac0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
19ad0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
19ae0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
19af0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
19b00 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
19b10 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
19b20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
19b30 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
19b40 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
19b50 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
19b60 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
19b70 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
19b80 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
19b90 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
19ba0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
19bb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
19bc0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
19bd0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
19be0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
19bf0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
19c00 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
19c10 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
19c20 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19c30 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19c40 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19c50 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
19c60 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
19c70 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
19c80 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
19c90 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
19ca0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
19cb0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
19cc0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
19cd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19ce0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
19cf0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
19d00 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
19d10 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
19d20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
19d30 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
19d40 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
19d50 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
19d60 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
19d70 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
19d80 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
19d90 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
19da0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
19db0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
19dc0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
19dd0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
19de0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
19df0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
19e00 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19e10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19e20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19e30 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
19e40 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
19e50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
19e60 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
19e70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
19e80 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
19e90 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
19ea0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
19eb0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
19ec0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
19ed0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
19ee0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
19ef0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
19f00 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
19f10 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
19f20 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
19f30 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
19f40 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
19f50 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
19f60 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
19f70 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
19f80 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
19f90 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
19fa0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
19fb0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
19fc0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
19fd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
19fe0 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
19ff0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1a000 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1a010 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1a020 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1a030 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1a040 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1a050 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1a060 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1a070 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1a080 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1a090 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1a0a0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1a0b0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1a0c0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1a0d0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1a0e0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1a0f0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1a100 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1a110 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1a120 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1a130 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1a140 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1a150 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a160 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1a170 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1a180 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a190 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1a1a0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1a1b0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1a1c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1a1d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1a1e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1a1f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1a200 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1a210 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a220 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1a230 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a240 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1a250 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1a260 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1a270 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1a280 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1a290 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1a2a0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1a2b0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1a2c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1a2d0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1a2e0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1a2f0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1a300 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1a310 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1a320 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1a330 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
1a340 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1a350 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1a360 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1a370 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1a380 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1a390 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1a3a0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
1a3b0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1a3c0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1a3d0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1a3e0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1a3f0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1a400 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1a410 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1a420 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1a430 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1a440 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1a450 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1a460 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1a470 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1a480 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1a490 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1a4a0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1a4b0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1a4c0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1a4d0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1a4e0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a4f0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a500 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1a510 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1a520 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1a530 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1a540 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1a550 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1a560 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
1a570 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
1a580 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
1a590 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1a5a0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1a5b0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1a5c0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1a5d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a5e0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a5f0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1a600 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1a610 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1a620 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1a630 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a640 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1a650 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1a660 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1a670 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1a680 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1a690 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
1a6a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1a6b0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1a6c0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1a6d0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1a6e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a6f0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1a700 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1a710 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1a720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1a730 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1a740 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1a750 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1a760 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1a770 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1a780 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a790 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1a7a0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1a7b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a7c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1a7d0 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1a7e0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1a7f0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1a800 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1a810 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1a820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a830 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1a840 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1a850 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1a860 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1a870 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1a880 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1a890 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1a8a0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1a8b0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1a8c0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1a8d0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1a8e0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1a8f0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1a900 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1a910 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1a920 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1a930 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1a940 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1a950 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1a960 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1a970 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1a980 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1a990 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1a9a0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1a9b0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1a9c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1a9d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1a9e0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1a9f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1aa00 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1aa10 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1aa20 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1aa30 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1aa40 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1aa50 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1aa60 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1aa70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1aa80 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1aa90 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1aaa0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1aab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1aac0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1aad0 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1aae0 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1aaf0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ab00 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1ab10 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1ab20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1ab30 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1ab40 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1ab50 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1ab60 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1ab70 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1ab80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ab90 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1aba0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1abb0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1abc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1abd0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1abe0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1abf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ac00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ac10 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1ac20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1ac30 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1ac40 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1ac50 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1ac60 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1ac70 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1ac80 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1ac90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aca0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1acb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1acc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1acd0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1ace0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1acf0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1ad00 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1ad10 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1ad20 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ad30 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1ad40 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1ad50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1ad60 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1ad70 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1ad80 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1ad90 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  E] flags:)^.**.*
1ada0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1adb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1adc0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1add0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1ade0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1adf0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1ae00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1ae10 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1ae20 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1ae30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1ae40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1ae50 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1ae60 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1ae70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1ae80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1ae90 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1aea0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1aeb0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1aec0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1aed0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1aee0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1aef0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1af00 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1af10 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1af20 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1af30 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1af40 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1af50 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1af60 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1af70 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1af80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1af90 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1afa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1afb0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1afc0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1afd0 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
1afe0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1aff0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1b000 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1b010 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1b020 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1b030 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1b040 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b050 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1b060 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1b070 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1b080 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1b090 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1b0a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1b0b0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1b0c0 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74  bove or one of t
1b0d0 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  he combinations 
1b0e0 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62  shown above comb
1b0f0 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ined.** with the
1b100 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b110 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1b120 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1b130 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1b140 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e  _SHAREDCACHE] an
1b150 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1b160 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1b170 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
1b180 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1b190 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1b1a0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1b1b0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1b1c0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1b1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b1e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1b1f0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1b200 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1b210 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1b220 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1b230 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1b240 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1b250 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1b260 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1b270 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1b280 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1b290 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1b2a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b2b0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1b2c0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1b2d0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1b2e0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1b2f0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1b300 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1b310 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1b320 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1b330 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1b340 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1b350 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1b360 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b370 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1b380 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1b390 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1b3a0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1b3b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1b3c0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1b3d0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1b3e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1b3f0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1b400 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1b410 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1b420 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1b430 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1b440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1b450 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1b460 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1b470 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1b480 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1b490 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b4a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1b4b0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1b4c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1b4d0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1b4e0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1b4f0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1b500 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
1b510 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b520 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1b530 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1b540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1b550 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1b560 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1b570 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1b580 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1b590 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1b5a0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1b5b0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1b5c0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1b5d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1b5e0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1b5f0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1b600 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1b610 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1b620 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1b630 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1b640 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1b650 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1b660 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1b670 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1b680 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1b690 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1b6a0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1b6b0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1b6c0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1b6d0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1b6e0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1b6f0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1b700 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1b710 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1b720 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1b730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b740 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1b750 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1b760 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b770 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1b780 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1b790 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1b7a0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1b7b0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1b7c0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1b7d0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1b7e0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1b7f0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1b800 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1b810 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1b820 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1b830 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1b840 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1b850 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1b860 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1b870 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1b880 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1b890 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1b8a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1b8b0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1b8c0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1b8d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1b8e0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1b8f0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1b900 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1b910 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1b920 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1b930 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1b940 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1b950 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1b960 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1b970 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1b980 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1b990 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1b9a0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
1b9b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1b9c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1b9d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1b9e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1b9f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1ba00 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1ba10 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1ba20 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1ba30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1ba40 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1ba50 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1ba60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1ba70 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1ba80 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1ba90 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1baa0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1bab0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1bac0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1bad0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1bae0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1baf0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1bb00 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1bb10 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1bb20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1bb30 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1bb40 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1bb50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1bb60 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1bb70 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1bb80 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1bb90 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1bba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bbb0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1bbc0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1bbd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bbe0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1bbf0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1bc00 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1bc10 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1bc20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1bc30 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1bc40 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1bc50 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1bc60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1bc70 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1bc80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1bc90 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1bca0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1bcb0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1bcc0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1bcd0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1bce0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1bcf0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1bd00 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1bd10 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1bd20 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1bd30 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1bd40 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1bd50 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1bd60 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1bd70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1bd80 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1bd90 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1bda0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1bdb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1bdc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1bdd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1bde0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1bdf0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1be00 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1be10 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1be20 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1be30 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1be40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1be50 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1be60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1be70 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1be80 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1be90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1bea0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1beb0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1bec0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1bed0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1bee0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1bef0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1bf00 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1bf10 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1bf20 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1bf30 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1bf40 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1bf50 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1bf60 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1bf70 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1bf80 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1bf90 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1bfa0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1bfb0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1bfc0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1bfd0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1bfe0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1bff0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1c000 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1c010 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1c020 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1c030 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1c040 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1c050 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1c060 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1c070 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1c080 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1c090 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1c0a0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1c0b0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1c0c0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1c0d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c0e0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1c0f0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1c100 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1c110 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1c120 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1c130 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1c140 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1c150 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1c160 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1c170 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1c180 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1c190 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1c1a0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1c1b0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1c1c0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1c1d0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1c1e0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1c1f0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1c200 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1c210 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1c220 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1c230 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1c240 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1c250 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1c260 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1c270 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1c280 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1c290 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1c2a0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1c2b0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1c2c0 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1c2d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1c2e0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1c2f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1c300 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1c310 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c320 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1c330 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1c340 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1c350 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1c360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c370 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1c380 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1c390 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1c3a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1c3b0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1c3c0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1c3d0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1c3e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c3f0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1c400 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1c410 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1c420 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1c430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1c440 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1c450 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1c460 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1c470 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1c480 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1c490 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1c4a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c4b0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1c4c0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1c4d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1c4e0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1c4f0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1c500 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1c510 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1c520 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1c530 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1c540 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c550 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1c560 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1c570 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1c580 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1c590 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1c5a0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1c5b0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1c5c0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1c5d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1c5e0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1c5f0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1c600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1c610 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1c620 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1c630 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1c640 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1c650 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1c660 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1c670 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1c680 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1c690 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1c6a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c6b0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1c6c0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1c6d0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1c6e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1c6f0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1c700 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1c710 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1c720 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1c730 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1c740 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1c750 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1c760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1c770 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1c780 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1c790 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1c7a0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1c7b0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1c7c0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1c7d0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1c7e0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1c7f0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1c800 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1c810 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1c820 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1c830 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
1c840 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
1c850 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1c860 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1c870 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1c880 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
1c890 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
1c8a0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
1c8b0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
1c8c0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
1c8d0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
1c8e0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
1c8f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1c900 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
1c910 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
1c920 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
1c930 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
1c940 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
1c950 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
1c960 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
1c970 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
1c980 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
1c990 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
1c9a0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
1c9b0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
1c9c0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
1c9d0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
1c9e0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
1c9f0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
1ca00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1ca10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1ca20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
1ca30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1ca40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1ca50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
1ca60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1ca70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
1ca80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
1ca90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
1caa0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
1cab0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
1cac0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
1cad0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
1cae0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1caf0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
1cb00 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
1cb10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1cb20 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1cb30 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1cb40 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1cb50 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1cb60 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1cb70 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1cb80 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1cb90 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1cba0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1cbb0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1cbc0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1cbd0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
1cbe0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1cbf0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1cc00 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1cc10 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1cc20 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1cc30 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1cc40 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1cc50 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1cc60 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1cc70 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1cc80 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1cc90 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1cca0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1ccb0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1ccc0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1ccd0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1cce0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1ccf0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1cd00 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1cd10 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1cd20 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1cd30 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1cd40 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1cd50 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1cd60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1cd70 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1cd80 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1cd90 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1cda0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1cdb0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1cdc0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1cdd0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1cde0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1cdf0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1ce00 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1ce10 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1ce20 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1ce30 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1ce40 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1ce50 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
1ce60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1ce70 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1ce80 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1ce90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cea0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1ceb0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
1cec0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1ced0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
1cee0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1cef0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1cf00 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1cf10 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
1cf20 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
1cf30 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
1cf40 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
1cf50 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1cf60 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
1cf70 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
1cf80 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1cf90 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
1cfa0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
1cfb0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1cfc0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
1cfd0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
1cfe0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
1cff0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1d000 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d010 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1d020 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
1d030 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
1d040 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
1d050 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
1d060 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  .<dd>)^.**.** ^(
1d070 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d080 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1d090 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d0a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1d0b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d0c0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
1d0d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d0e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1d0f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d100 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d110 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
1d120 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
1d130 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
1d140 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1d150 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
1d160 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d170 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1d180 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1d190 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1d1a0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1d1b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d1c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1d1d0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1d1e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d1f0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
1d200 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
1d210 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
1d220 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d230 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1d240 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1d250 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d260 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1d270 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1d280 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1d290 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
1d2a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d2b0 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
1d2c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d2d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
1d2e0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
1d2f0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
1d300 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
1d310 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
1d320 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
1d330 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
1d340 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
1d350 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
1d360 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
1d370 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
1d380 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
1d390 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
1d3a0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d3b0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1d3c0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1d3d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d3e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1d3f0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1d400 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1d410 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d420 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1d430 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d440 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1d450 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1d460 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
1d470 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d480 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1d490 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1d4a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d4b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1d4c0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1d4d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
1d4e0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
1d4f0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
1d500 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d510 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1d520 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1d530 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d540 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
1d550 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
1d560 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
1d570 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
1d580 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d590 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1d5a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d5b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1d5c0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1d5d0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1d5e0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1d5f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d600 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1d610 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1d620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d630 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1d640 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1d650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d660 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1d670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1d680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d690 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1d6a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1d6b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d6c0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1d6d0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1d6e0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1d6f0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1d700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d710 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1d720 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1d730 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1d740 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1d750 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1d760 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1d770 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1d780 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1d790 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1d7a0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1d7b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1d7c0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1d7d0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1d7e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1d7f0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1d800 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1d810 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1d820 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1d830 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1d840 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1d850 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1d860 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1d870 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1d880 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1d890 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1d8a0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1d8b0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1d8c0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1d8d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1d8e0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1d8f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d900 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1d910 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1d920 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1d930 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1d940 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1d950 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1d960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d970 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1d980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1d990 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1d9a0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1d9b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1d9c0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1d9d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1d9e0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1d9f0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1da00 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1da10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1da20 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1da30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1da40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1da50 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1da60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1da70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1da80 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1da90 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1daa0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1dab0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1dac0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1dad0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1dae0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1daf0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1db00 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1db10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1db20 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1db30 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1db40 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1db50 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1db60 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1db70 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1db80 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1db90 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1dba0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1dbb0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1dbc0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1dbd0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1dbe0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1dbf0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1dc00 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1dc10 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1dc20 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1dc30 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1dc40 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1dc50 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1dc60 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1dc70 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1dc80 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1dc90 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1dca0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1dcb0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1dcc0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1dcd0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1dce0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1dcf0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1dd00 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1dd10 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1dd20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1dd30 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1dd40 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1dd50 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1dd60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1dd70 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1dd80 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1dd90 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1dda0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1ddb0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1ddc0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1ddd0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1dde0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1ddf0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1de00 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1de10 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1de20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1de30 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1de40 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1de50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1de60 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1de70 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1de80 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1de90 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1dea0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1deb0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1dec0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1ded0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1dee0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1def0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1df00 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1df10 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1df20 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1df30 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1df40 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1df50 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1df60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1df70 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1df80 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1df90 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1dfa0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1dfb0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1dfc0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1dfd0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1dfe0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1dff0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1e000 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1e010 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1e020 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e030 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1e040 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1e050 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e060 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1e070 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1e080 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1e090 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1e0a0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1e0b0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1e0c0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1e0d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1e0e0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1e0f0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1e100 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1e110 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1e120 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1e130 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1e140 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1e150 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1e160 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1e170 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1e180 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1e190 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1e1a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1e1b0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1e1c0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1e1d0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1e1e0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1e1f0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1e200 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1e210 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1e220 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1e230 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1e240 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1e250 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1e260 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1e270 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1e280 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1e290 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1e2a0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1e2b0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
1e2c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
1e2d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1e2e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e2f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1e300 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1e310 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1e320 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1e330 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
1e340 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1e350 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
1e360 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e370 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1e380 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
1e390 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1e3a0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
1e3b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
1e3c0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1e3d0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1e3e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1e3f0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
1e400 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1e410 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1e420 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1e430 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1e440 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1e450 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1e460 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1e470 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e480 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1e490 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1e4a0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
1e4b0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
1e4c0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
1e4d0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1e4e0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
1e4f0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
1e500 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
1e510 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
1e520 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
1e530 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
1e540 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
1e550 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
1e560 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
1e570 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1e580 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
1e590 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
1e5a0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
1e5b0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1e5c0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1e5d0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
1e5e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e5f0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
1e600 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
1e610 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
1e620 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
1e630 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
1e640 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
1e650 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
1e660 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
1e670 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e680 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
1e690 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
1e6a0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
1e6b0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
1e6c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
1e6d0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
1e6e0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
1e6f0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
1e700 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63  _ENABLE_STAT2] c
1e710 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1e720 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
1e730 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
1e740 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
1e750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e760 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1e770 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1e780 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1e790 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1e7a0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1e7b0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1e7c0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1e7d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1e7e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1e7f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1e800 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1e810 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1e820 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1e830 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1e840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1e850 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1e860 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1e870 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1e880 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1e890 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1e8a0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1e8b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1e8c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1e8d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1e8e0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1e8f0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1e900 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1e910 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1e920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1e930 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1e940 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1e950 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1e960 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1e970 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1e980 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e990 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1e9a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1e9b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1e9c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1e9d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1e9e0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1e9f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1ea00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1ea10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1ea20 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1ea30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1ea40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1ea50 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1ea60 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1ea70 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1ea80 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ea90 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1eaa0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1eab0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1eac0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ead0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1eae0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1eaf0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1eb00 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1eb10 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1eb20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1eb30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1eb40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1eb50 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1eb60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1eb70 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1eb80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1eb90 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1eba0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1ebb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ebc0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1ebd0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1ebe0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1ebf0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1ec00 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1ec10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ec20 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1ec30 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1ec40 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1ec50 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1ec60 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ec70 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1ec80 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
1ec90 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
1eca0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
1ecb0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
1ecc0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
1ecd0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
1ece0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
1ecf0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
1ed00 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
1ed10 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
1ed20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
1ed30 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1ed40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ed50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1ed60 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
1ed70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1ed80 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
1ed90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1eda0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1edb0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1edc0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
1edd0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
1ede0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
1edf0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
1ee00 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
1ee10 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
1ee20 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 74 68  n-zero) if.** th
1ee30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1ee40 65 6d 65 6e 74 5d 20 58 20 69 73 20 5b 53 45 4c  ement] X is [SEL
1ee50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
1ee60 6e 64 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 20  nd false (zero) 
1ee70 69 66 0a 2a 2a 20 58 20 69 73 20 61 6e 20 5b 49  if.** X is an [I
1ee80 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1ee90 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 43 52 45 41  , [DELETE], CREA
1eea0 54 45 2c 20 44 52 4f 50 2c 20 5b 41 4e 41 4c 59  TE, DROP, [ANALY
1eeb0 5a 45 5d 2c 0a 2a 2a 20 5b 41 4c 54 45 52 5d 2c  ZE],.** [ALTER],
1eec0 20 6f 72 20 5b 52 45 49 4e 44 45 58 5d 20 73 74   or [REINDEX] st
1eed0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 49 66 20 58  atement..** If X
1eee0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1eef0 65 72 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20  er or any other 
1ef00 6b 69 6e 64 20 6f 66 20 73 74 61 74 65 6d 65 6e  kind of statemen
1ef10 74 2c 20 69 6e 63 6c 75 64 69 6e 67 20 62 75 74  t, including but
1ef20 0a 2a 2a 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20  .** not limited 
1ef30 74 6f 20 5b 41 54 54 41 43 48 5d 2c 20 5b 44 45  to [ATTACH], [DE
1ef40 54 41 43 48 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  TACH], [COMMIT],
1ef50 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 20 5b 52 45   [ROLLBACK], [RE
1ef60 4c 45 41 53 45 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LEASE],.** [SAVE
1ef70 50 4f 49 4e 54 5d 2c 20 5b 50 52 41 47 4d 41 5d  POINT], [PRAGMA]
1ef80 2c 20 6f 72 20 5b 56 41 43 55 55 4d 5d 20 74 68  , or [VACUUM] th
1ef90 65 20 72 65 73 75 6c 74 20 6f 66 20 73 71 6c 69  e result of sqli
1efa0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
1efb0 79 28 58 29 20 69 73 0a 2a 2a 20 75 6e 64 65 66  y(X) is.** undef
1efc0 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
1efd0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
1efe0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
1eff0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1f000 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
1f010 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1f020 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
1f030 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
1f040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
1f050 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
1f060 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
1f070 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
1f080 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1f090 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
1f0a0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
1f0b0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
1f0c0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
1f0d0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
1f0e0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
1f0f0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
1f100 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
1f110 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
1f120 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1f130 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1f140 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1f150 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1f160 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1f170 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1f180 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1f190 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1f1a0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1f1b0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1f1c0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1f1d0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1f1e0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1f1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1f200 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1f210 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1f220 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1f230 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1f240 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f250 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1f260 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1f270 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1f280 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1f290 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1f2a0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1f2b0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1f2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1f2d0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1f2e0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1f2f0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1f300 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1f310 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1f320 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1f330 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1f340 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1f350 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1f360 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1f370 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1f380 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1f390 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1f3a0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1f3b0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1f3c0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1f3d0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1f3e0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1f3f0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1f400 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1f410 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1f420 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
1f430 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
1f440 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
1f450 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
1f460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1f470 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
1f480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1f490 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
1f4a0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1f4b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1f4c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1f4d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1f4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1f4f0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1f500 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
1f510 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
1f520 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
1f530 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1f540 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
1f550 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1f560 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
1f570 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
1f580 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
1f590 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1f5a0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1f5b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f5c0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
1f5d0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
1f5e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1f5f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1f600 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1f610 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1f620 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1f630 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f640 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1f650 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1f660 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1f670 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
1f680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1f690 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1f6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1f6b0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1f6c0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1f6d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1f6e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1f6f0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1f700 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1f710 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1f720 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1f730 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1f740 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1f750 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1f760 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1f770 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1f780 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1f790 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f7a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1f7b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1f7c0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1f7d0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1f7e0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1f7f0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1f800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
1f810 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
1f820 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
1f830 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
1f840 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
1f850 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
1f860 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
1f870 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1f880 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1f890 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1f8a0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1f8b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1f8c0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1f8d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1f8e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1f8f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1f900 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1f910 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1f920 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1f930 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1f940 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1f950 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1f960 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1f970 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1f980 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1f990 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1f9a0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1f9b0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1f9c0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1f9d0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1f9e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1f9f0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1fa00 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1fa10 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1fa20 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1fa30 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1fa40 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1fa50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
1fa60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1fa70 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1fa80 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1fa90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1faa0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1fab0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1fac0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1fad0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1fae0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
1faf0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
1fb00 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
1fb10 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1fb20 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
1fb30 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
1fb40 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
1fb50 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
1fb60 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
1fb70 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
1fb80 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
1fb90 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
1fba0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
1fbb0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
1fbc0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
1fbd0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
1fbe0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
1fbf0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
1fc00 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
1fc10 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
1fc20 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
1fc30 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
1fc40 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
1fc50 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
1fc60 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
1fc70 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1fc80 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1fc90 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1fca0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1fcb0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1fcc0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1fcd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1fce0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1fcf0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1fd00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1fd10 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1fd20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1fd30 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1fd40 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1fd50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1fd60 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1fd70 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1fd80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1fd90 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1fda0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1fdb0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1fdc0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1fdd0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1fde0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1fdf0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
1fe00 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1fe10 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1fe20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
1fe30 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
1fe40 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1fe50 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1fe60 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1fe70 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1fe80 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1fe90 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1fea0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
1feb0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
1fec0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1fed0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1fee0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1fef0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ff00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ff10 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1ff20 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
1ff30 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1ff40 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1ff50 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
1ff60 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1ff70 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1ff80 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1ff90 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1ffa0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1ffb0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1ffc0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1ffd0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1ffe0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
1fff0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
20000 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
20010 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
20020 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
20030 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
20040 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
20050 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
20060 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
20070 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
20080 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
20090 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
200a0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
200b0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
200c0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
200d0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
200e0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
200f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
20100 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
20110 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
20120 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
20130 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
20140 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
20150 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
20160 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
20170 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
20180 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
20190 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
201a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
201b0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
201c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
201d0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
201e0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
201f0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
20200 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
20210 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
20220 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
20230 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
20240 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
20250 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20260 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
20270 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
20280 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
20290 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
202a0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
202b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
202c0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
202d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
202e0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
202f0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
20300 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
20310 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
20320 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
20330 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
20340 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
20350 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
20360 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
20370 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
20380 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
20390 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
203a0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
203b0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
203c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
203d0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
203e0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
203f0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
20400 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
20410 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20420 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
20430 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
20440 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
20450 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
20460 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
20470 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
20480 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
20490 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
204a0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
204b0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
204c0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
204d0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
204e0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
204f0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
20500 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
20510 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
20520 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
20530 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
20540 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
20550 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
20560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
20570 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
20580 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
20590 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
205a0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
205b0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
205c0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
205d0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
205e0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
205f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20600 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
20610 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
20620 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
20630 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
20640 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
20650 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
20660 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
20670 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
20680 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
20690 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
206a0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
206b0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
206c0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
206d0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
206e0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
206f0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
20700 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
20710 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
20720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
20730 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
20740 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
20750 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
20760 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
20770 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
20780 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
20790 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
207a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
207b0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
207c0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
207d0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
207e0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
207f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
20800 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
20810 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
20820 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
20830 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
20840 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
20850 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
20860 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
20870 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
20880 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
20890 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
208a0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
208b0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
208c0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
208d0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
208e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
208f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
20900 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
20910 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20920 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
20930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
20940 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
20950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
20960 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
20970 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
20980 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
20990 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
209a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
209b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
209c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
209d0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
209e0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
209f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20a00 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
20a10 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
20a20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20a30 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
20a40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20a50 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
20a60 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
20a70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20a80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
20a90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
20aa0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
20ab0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
20ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20ad0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20ae0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
20af0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
20b00 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20b10 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
20b20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20b30 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
20b40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
20b50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
20b60 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
20b70 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
20b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20b90 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
20ba0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
20bb0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
20bc0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
20bd0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
20be0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
20bf0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
20c00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
20c10 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
20c20 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
20c30 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
20c40 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
20c50 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
20c60 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
20c70 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
20c80 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
20c90 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
20ca0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
20cb0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
20cc0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
20cd0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
20ce0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
20cf0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
20d00 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
20d10 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
20d20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
20d30 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
20d40 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
20d50 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
20d60 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
20d70 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
20d80 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
20d90 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
20da0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
20db0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
20dc0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
20dd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
20de0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
20df0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
20e00 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
20e10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20e20 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
20e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20e40 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20e50 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
20e60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20e70 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
20e80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
20e90 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
20ea0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
20eb0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
20ec0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20ed0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
20ee0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
20ef0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
20f00 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
20f10 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
20f20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20f30 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
20f40 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
20f50 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
20f60 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
20f70 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
20f80 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
20f90 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
20fa0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
20fb0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
20fc0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
20fd0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
20fe0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
20ff0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
21000 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
21010 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
21020 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
21030 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
21040 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
21050 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
21060 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
21070 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
21080 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
21090 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
210a0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
210b0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
210c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
210d0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
210e0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
210f0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
21100 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
21110 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
21120 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
21130 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
21140 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
21150 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
21160 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21170 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
21180 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
21190 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
211a0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
211b0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
211c0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
211d0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
211e0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
211f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21200 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
21210 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21220 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
21230 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
21240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21250 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21260 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
21270 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21280 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
21290 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
212a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
212b0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
212c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
212d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
212e0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
212f0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
21300 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
21310 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
21320 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
21330 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
21340 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
21350 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
21360 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
21370 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
21380 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
21390 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
213a0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
213b0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
213c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
213d0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
213e0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
213f0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
21400 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
21410 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
21420 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
21430 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
21440 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
21450 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
21460 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
21470 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
21480 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21490 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
214a0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
214b0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
214c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
214d0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
214e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
214f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21500 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21510 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21520 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
21530 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
21540 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
21550 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
21560 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
21570 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
21580 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
21590 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
215a0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
215b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
215c0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
215d0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
215e0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
215f0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
21600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21610 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
21620 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
21630 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
21640 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
21650 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
21660 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
21670 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
21680 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
21690 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
216a0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
216b0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
216c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
216d0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
216e0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
216f0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
21700 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
21710 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
21720 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
21730 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
21740 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
21750 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
21760 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
21770 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
21780 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
21790 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
217a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
217b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
217c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
217d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
217e0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
217f0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
21800 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
21810 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
21820 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
21830 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
21840 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
21850 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
21860 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
21870 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
21880 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
21890 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
218a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
218b0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
218c0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
218d0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
218e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
218f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
21900 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
21910 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
21920 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
21930 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
21940 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
21950 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
21960 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
21970 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
21980 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
21990 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
219a0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
219b0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
219c0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
219d0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
219e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
219f0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
21a00 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
21a10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21a20 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
21a30 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
21a40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21a50 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
21a60 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
21a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
21a80 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
21a90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
21aa0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
21ab0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
21ac0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
21ad0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
21ae0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
21af0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
21b00 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
21b10 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
21b20 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
21b30 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
21b40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
21b50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
21b60 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
21b70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
21b80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
21b90 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
21ba0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
21bb0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
21bc0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
21bd0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
21be0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
21bf0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
21c00 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
21c10 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
21c20 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
21c30 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
21c40 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
21c50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
21c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
21c70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21c80 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
21c90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21ca0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
21cb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
21cc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21cd0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
21ce0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
21cf0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
21d00 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
21d10 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
21d20 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
21d30 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
21d40 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
21d50 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
21d60 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
21d70 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
21d80 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
21d90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
21da0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
21db0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
21dc0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
21dd0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
21de0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
21df0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
21e00 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
21e10 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
21e20 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
21e30 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
21e40 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
21e50 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
21e60 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
21e70 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
21e80 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
21e90 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
21ea0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21eb0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
21ec0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21ed0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
21ee0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
21ef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21f00 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
21f10 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
21f20 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
21f30 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
21f40 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
21f50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
21f60 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
21f70 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
21f80 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
21f90 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
21fa0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
21fb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
21fc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
21fd0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
21fe0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
21ff0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
22000 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
22010 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
22020 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
22030 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
22040 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
22050 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
22060 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
22070 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
22080 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
22090 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
220a0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
220b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
220c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
220d0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
220e0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
220f0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
22100 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
22110 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
22120 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
22130 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
22140 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
22150 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
22160 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
22170 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
22180 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
22190 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
221a0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
221b0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
221c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
221d0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
221e0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
221f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
22200 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
22210 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
22220 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
22230 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
22240 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
22250 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
22260 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
22270 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
22280 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
22290 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
222a0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
222b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
222c0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
222d0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
222e0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
222f0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
22300 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
22310 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
22320 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
22330 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
22340 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
22350 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
22360 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
22370 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
22380 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
22390 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
223a0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
223b0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
223c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
223d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
223e0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
223f0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
22400 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
22410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
22420 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
22430 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
22440 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
22450 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
22460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
22470 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
22480 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
22490 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
224a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
224b0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
224c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
224d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
224e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
224f0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
22500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22510 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
22520 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22530 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
22540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
22550 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
22560 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
22570 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22580 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
22590 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
225a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
225b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
225c0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
225d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
225e0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
225f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
22600 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
22610 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22630 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
22640 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
22650 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
22660 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
22670 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
22680 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
22690 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
226a0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
226b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
226c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
226d0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
226e0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
226f0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
22700 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
22710 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
22720 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
22730 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
22740 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
22750 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
22760 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
22770 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
22780 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
22790 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
227a0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
227b0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
227c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
227d0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
227e0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
227f0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
22800 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
22810 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
22820 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
22830 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
22840 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
22850 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
22860 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
22870 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
22880 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
22890 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
228a0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
228b0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
228c0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
228d0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
228e0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
228f0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
22900 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
22910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
22920 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
22930 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
22940 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
22950 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
22960 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
22970 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
22980 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
22990 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
229a0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
229b0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
229c0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
229d0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
229e0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
229f0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
22a00 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
22a10 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
22a20 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
22a30 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
22a40 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
22a50 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
22a60 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
22a70 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
22a80 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
22a90 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
22aa0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
22ab0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
22ad0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
22ae0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
22af0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22b00 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
22b10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22b20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22b30 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
22b40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
22b50 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
22b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22b70 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
22b80 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
22b90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
22ba0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
22bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22bc0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
22bd0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
22be0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
22bf0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
22c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22c10 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
22c20 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
22c30 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
22c40 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
22c50 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
22c60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
22c70 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
22c80 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
22c90 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
22ca0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
22cb0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
22cc0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
22cd0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
22ce0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
22cf0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
22d00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
22d10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
22d20 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
22d30 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
22d40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
22d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
22d60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
22d70 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
22d80 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
22d90 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
22da0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
22db0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
22dc0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
22dd0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
22de0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
22df0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
22e00 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
22e10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22e20 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
22e30 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
22e40 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
22e50 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
22e60 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
22e70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
22e80 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
22e90 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
22ea0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
22eb0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
22ec0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
22ed0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
22ee0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
22ef0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
22f00 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
22f10 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
22f20 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
22f30 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
22f40 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
22f50 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
22f60 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
22f70 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
22f80 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
22f90 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
22fa0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
22fb0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
22fc0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
22fd0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
22fe0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
22ff0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
23000 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
23010 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
23020 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
23030 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
23040 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
23050 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
23060 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
23070 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
23080 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
23090 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
230a0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
230b0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
230c0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
230d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
230e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
230f0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
23100 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
23110 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
23120 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
23130 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
23140 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
23150 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
23160 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
23170 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
23180 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
23190 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
231a0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
231b0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
231c0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
231d0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
231e0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
231f0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
23200 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
23210 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
23220 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
23230 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
23240 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
23250 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
23260 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
23270 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
23280 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
23290 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
232a0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
232b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
232c0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
232d0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
232e0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
232f0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
23300 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
23310 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
23320 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
23330 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
23340 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
23350 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
23360 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
23370 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
23380 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
23390 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
233a0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
233b0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
233c0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
233d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
233e0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
233f0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
23400 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
23410 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
23420 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
23430 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
23440 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
23450 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
23460 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
23470 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
23480 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
23490 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
234a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
234b0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
234c0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
234d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
234e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
234f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
23500 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
23510 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
23520 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
23530 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
23540 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
23550 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
23560 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
23570 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
23580 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
23590 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
235a0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
235b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
235c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
235d0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
235e0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
235f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
23600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
23610 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
23620 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
23630 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
23640 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
23650 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
23660 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23670 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
23680 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 69  ding 3.6.23.1, i
23690 74 20 77 61 73 20 72 65 71 75 69 72 65 64 0a 2a  t was required.*
236a0 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  * after sqlite3_
236b0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
236c0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
236d0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
236e0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
236f0 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20 63 61  3_reset()] be ca
23700 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e 79 20  lled before any 
23710 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
23720 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
23730 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
23740 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b  lure to invoke [
23750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23760 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 6f 75   in this way wou
23770 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ld.** result in 
23780 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
23790 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 73  E] return from s
237a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
237b0 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76 65 72  But after.** ver
237c0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
237d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
237e0 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  gan calling [sql
237f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 0a 2a  ite3_reset()] .*
23800 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
23810 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
23820 61 6e 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  ance rather than
23830 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
23840 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a 2a 2a  TE_MISUSE].  .**
23850 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
23860 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
23870 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
23880 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
23890 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
238a0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
238b0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
238c0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
238d0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
238e0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
238f0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
23900 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
23910 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
23920 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
23930 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23940 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
23950 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
23960 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
23970 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
23980 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
23990 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
239a0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
239b0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
239c0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
239d0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
239e0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
239f0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
23a00 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
23a10 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
23a20 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
23a30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
23a40 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
23a50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23a60 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
23a70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
23a80 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
23a90 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
23aa0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
23ab0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
23ac0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
23ad0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
23ae0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
23af0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
23b00 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
23b10 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
23b20 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
23b30 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
23b40 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
23b50 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
23b60 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
23b70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
23b80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
23b90 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
23ba0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
23bb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23bc0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
23bd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23be0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
23bf0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
23c00 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
23c10 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
23c20 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
23c30 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
23c40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23c50 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
23c60 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
23c70 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
23c80 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
23c90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23ca0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
23cb0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
23cc0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
23cd0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
23ce0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
23cf0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
23d00 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
23d10 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
23d20 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
23d30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
23d40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23d50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23d60 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
23d70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
23d80 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
23d90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
23da0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
23db0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
23dc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
23dd0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
23de0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
23df0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
23e00 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
23e10 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
23e20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
23e30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
23e40 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
23e50 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
23e60 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
23e70 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
23e80 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
23e90 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
23ea0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
23eb0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
23ec0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
23ed0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
23ee0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
23ef0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
23f00 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
23f10 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
23f20 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
23f30 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
23f40 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
23f50 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
23f60 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
23f70 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
23f80 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
23f90 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
23fa0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
23fb0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
23fc0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
23fd0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
23fe0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
23ff0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
24000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
24010 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
24020 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
24030 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
24040 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
24050 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
24060 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
24070 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
24080 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
24090 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
240a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
240b0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
240c0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
240d0 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
240e0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
240f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24100 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
24110 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
24120 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
24130 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
24140 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
24150 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
24160 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
24170 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
24180 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
24190 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
241a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
241b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
241c0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
241d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
241e0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
241f0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
24200 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
24210 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
24220 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
24230 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
24240 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
24250 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
24260 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
24270 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
24280 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
24290 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
242a0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
242b0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
242c0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
242d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
242e0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
242f0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
24300 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
24310 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
24320 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
24330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24340 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
24350 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
24360 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
24370 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
24380 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
24390 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
243a0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
243b0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
243c0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
243d0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
243e0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
243f0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
24400 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
24410 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
24420 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
24430 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
24440 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
24450 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
24460 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
24470 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
24480 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
24490 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
244a0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
244b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
244c0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
244d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
244e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
244f0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
24500 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24510 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
24520 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
24530 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
24540 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
24550 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
24560 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
24570 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
24580 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
24590 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
245a0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
245b0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
245c0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
245d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
245e0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
245f0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
24600 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
24610 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
24620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
24630 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
24640 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
24650 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
24660 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
24670 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
24680 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
24690 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
246a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
246b0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
246c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
246d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
246e0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
246f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
24700 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
24710 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
24720 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
24730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
24740 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
24750 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
24760 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
24770 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
24780 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
24790 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
247a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
247b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
247c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
247d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
247e0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
247f0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
24800 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
24810 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
24820 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
24830 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
24840 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
24850 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
24860 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
24870 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
24880 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
24890 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
248a0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
248b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
248c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
248d0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
248e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
248f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
24900 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
24910 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
24920 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
24930 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
24940 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
24950 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
24960 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
24970 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
24980 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
24990 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
249a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
249b0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
249c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
249d0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
249e0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
249f0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
24a00 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
24a10 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
24a20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
24a30 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
24a40 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
24a50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
24a60 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
24a70 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
24a80 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
24a90 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
24aa0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
24ab0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
24ac0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
24ad0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
24ae0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
24af0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
24b00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
24b10 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
24b20 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
24b30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24b40 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
24b50 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
24b60 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
24b70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
24b80 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
24b90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
24ba0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
24bb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
24bc0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
24bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
24be0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
24bf0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
24c00 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
24c10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
24c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
24c30 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
24c40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
24c50 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
24c60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
24c70 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
24c80 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
24c90 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
24ca0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
24cb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24cc0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
24cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24ce0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
24cf0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
24d00 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
24d10 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
24d20 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
24d30 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
24d40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
24d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24d60 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
24d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24d80 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
24d90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
24da0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
24db0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
24dc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
24dd0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
24de0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
24df0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24e00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
24e10 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
24e20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
24e30 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
24e40 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
24e50 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
24e60 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
24e70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
24e80 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
24e90 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
24ea0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
24eb0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
24ec0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
24ed0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
24ee0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
24ef0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24f00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
24f10 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
24f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24f30 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
24f40 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
24f50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
24f60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24f70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
24f80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
24f90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24fa0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
24fb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
24fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24fd0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
24fe0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
24ff0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
25000 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
25010 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
25020 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
25030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
25040 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
25050 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
25060 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
25070 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25080 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
25090 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
250a0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
250b0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
250c0 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
250d0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
250e0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
250f0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
25100 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
25110 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
25120 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
25130 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
25140 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
25150 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
25160 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
25170 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
25180 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
25190 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
251a0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
251b0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
251c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
251d0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
251e0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
251f0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
25200 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
25210 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
25220 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
25230 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
25240 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
25250 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
25260 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
25270 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
25280 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
25290 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
252a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
252b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
252c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
252d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
252e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
252f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
25300 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
25310 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
25320 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
25330 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
25340 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
25350 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
25360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
25370 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
25380 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
25390 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
253a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
253b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
253c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
253d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
253e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
253f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
25400 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
25410 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
25420 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
25430 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
25440 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
25450 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
25460 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
25470 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
25480 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
25490 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
254a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
254b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
254c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
254d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
254e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
254f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
25500 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
25510 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
25520 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
25530 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
25540 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
25550 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
25560 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
25570 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
25580 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
25590 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
255a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
255b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
255c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
255d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
255e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
255f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
25600 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
25610 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
25620 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
25630 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
25640 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
25650 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
25660 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
25670 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
25680 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
25690 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
256a0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
256b0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
256c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
256d0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
256e0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
256f0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
25700 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
25710 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
25720 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
25730 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
25740 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
25750 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
25760 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
25770 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
25780 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
25790 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
257a0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
257b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
257c0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
257d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
257e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
257f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
25800 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
25810 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
25820 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
25830 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
25840 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
25850 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
25860 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
25870 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
25880 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
25890 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
258a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
258b0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
258c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
258d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
258e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
258f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
25900 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
25910 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
25920 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
25930 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
25940 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
25950 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
25960 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
25970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
25980 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
25990 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
259a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
259b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
259c0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
259d0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
259e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
259f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
25a00 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
25a10 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
25a20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25a30 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
25a40 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
25a50 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
25a60 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
25a70 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
25a80 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
25a90 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
25aa0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
25ab0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
25ac0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
25ad0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
25ae0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
25af0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
25b00 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
25b10 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
25b20 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
25b30 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
25b40 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
25b50 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
25b60 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
25b70 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
25b80 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
25b90 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
25ba0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
25bb0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
25bc0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
25bd0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
25be0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
25bf0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
25c00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
25c10 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
25c20 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
25c30 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
25c40 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
25c50 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
25c60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
25c70 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
25c80 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
25c90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
25ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25cb0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
25cc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
25cd0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
25ce0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
25cf0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
25d00 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
25d10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
25d20 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
25d30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
25d40 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
25d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25d60 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
25d70 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
25d80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
25d90 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
25da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25db0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
25dc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
25dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25de0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
25df0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
25e00 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
25e10 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
25e20 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
25e30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25e40 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
25e50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25e60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
25e70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
25e80 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
25e90 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
25ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
25eb0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
25ec0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
25ed0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
25ee0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25ef0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
25f00 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
25f10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
25f20 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
25f30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
25f40 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
25f50 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
25f60 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
25f70 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
25f80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
25f90 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
25fa0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
25fb0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
25fc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
25fd0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
25fe0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25ff0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
26000 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
26010 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
26020 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
26030 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
26040 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
26050 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
26060 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
26070 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
26080 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
26090 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
260a0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
260b0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
260c0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
260d0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
260e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
260f0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
26100 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
26110 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
26120 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
26130 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
26140 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
26150 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
26160 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
26170 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
26180 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
26190 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
261a0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
261b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
261c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
261d0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
261e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
261f0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
26200 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26210 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
26220 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26230 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
26240 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
26250 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
26270 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
26280 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26290 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
262a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
262b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
262c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
262d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
262e0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
262f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26300 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
26310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
26320 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
26330 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
26340 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
26350 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26360 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
26370 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26380 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
263a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
263b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
263c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
263d0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
263e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
263f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
26400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
26410 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26420 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
26430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
26440 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
26450 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26470 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
26480 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
26490 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
264a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264b0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
264c0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
264d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
264e0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
264f0 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a  ed no errors or.
26500 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
26510 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
26520 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
26530 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
26540 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
26550 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
26560 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
26570 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
26580 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
26590 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
265a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
265b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
265c0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
265d0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
265e0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
265f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
26600 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
26610 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
26620 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
26630 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
26640 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
26650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26660 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
26670 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
26680 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
26690 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
266a0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
266b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
266c0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
266d0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
266e0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
266f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26700 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
26710 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
26720 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
26730 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
26740 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
26750 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
26760 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
26770 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
26780 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
26790 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
267a0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
267b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
267c0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
267d0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
267e0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
267f0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
26800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
26810 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
26820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26830 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
26840 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
26850 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
26860 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26870 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
26880 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
26890 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
268a0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
268b0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
268c0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
268d0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
268e0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
268f0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
26900 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
26910 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
26920 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
26930 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
26940 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
26950 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26960 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
26970 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
26980 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
26990 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
269a0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
269b0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
269c0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
269d0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
269e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
269f0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
26a00 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
26a10 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
26a20 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
26a30 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
26a40 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
26a50 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
26a60 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
26a70 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
26a80 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
26a90 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
26aa0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
26ab0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
26ac0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
26ad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26ae0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
26af0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
26b00 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
26b10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
26b20 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
26b30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
26b40 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
26b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26b60 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
26b70 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
26b80 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
26b90 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
26ba0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
26bb0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
26bc0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
26bd0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
26be0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
26bf0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
26c00 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
26c10 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
26c20 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
26c30 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
26c40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26c50 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
26c60 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
26c70 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
26c80 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
26c90 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
26ca0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
26cb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
26cc0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
26cd0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
26ce0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
26cf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26d00 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
26d10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26d20 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
26d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
26d40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
26d50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26d60 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
26d70 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
26d80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
26d90 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
26da0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
26db0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
26dc0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
26dd0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
26de0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
26df0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
26e00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
26e10 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
26e20 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
26e30 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
26e40 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
26e50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
26e60 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
26e70 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
26e80 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
26e90 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
26ea0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
26eb0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
26ec0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
26ed0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
26ee0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
26ef0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
26f00 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
26f10 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
26f20 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
26f30 65 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  e the second par
26f40 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
26f50 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
26f60 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
26f70 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
26f80 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
26f90 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
26fa0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
26fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
26fc0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
26fd0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
26fe0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
26ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27000 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
27010 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
27020 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
27030 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
27040 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
27050 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
27060 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
27070 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
27080 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27090 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
270a0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
270b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
270c0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
270d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
270e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
270f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
27100 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
27110 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
27120 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
27130 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
27140 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
27150 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
27160 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
27170 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
27180 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
27190 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
271a0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
271b0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
271c0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
271d0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
271e0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
271f0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
27200 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
27210 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
27220 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
27230 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
27240 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
27250 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
27260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
27270 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
27280 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
27290 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
272a0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
272b0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
272c0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
272d0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
272e0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
272f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
27300 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
27310 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
27320 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
27330 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
27340 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
27350 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
27360 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
27370 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
27380 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
27390 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
273a0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
273b0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
273c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
273d0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
273e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
273f0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
27400 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
27410 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
27420 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
27430 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
27440 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
27450 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
27460 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
27470 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
27480 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
27490 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
274a0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
274b0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
274c0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
274d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
274e0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
274f0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
27500 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
27510 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
27520 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
27530 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
27540 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27550 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
27560 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
27570 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
27580 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
27590 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
275a0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
275b0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
275c0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
275d0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
275e0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
275f0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
27600 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
27610 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
27620 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
27630 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
27640 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
27650 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
27660 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
27670 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
27680 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
27690 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
276a0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
276b0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
276c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
276d0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
276e0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
276f0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
27700 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
27710 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
27720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27730 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
27740 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
27750 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
27760 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
27770 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
27780 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 76  ^.**.** ^The sev
27790 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
277a0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
277b0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
277c0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
277d0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
277e0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
277f0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
27800 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
27810 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
27820 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
27830 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
27840 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
27850 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
27860 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
27870 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
27880 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
27890 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
278a0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
278b0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
278c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
278d0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
278e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
278f0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
27900 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
27910 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
27920 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
27930 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
27940 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
27950 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
27960 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
27970 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c   poiners for all
27980 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
27990 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
279a0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 74 65 6e  .** ^(If the ten
279b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
279c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
279d0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
279e0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
279f0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
27a00 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
27a10 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
27a20 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
27a30 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
27a40 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
27a50 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
27a60 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
27a70 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
27a80 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
27a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
27aa0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
27ab0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
27ac0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
27ad0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
27ae0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27af0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
27b00 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
27b10 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
27b20 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
27b30 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
27b40 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
27b50 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
27b60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
27b70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
27b80 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
27b90 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
27ba0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
27bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27bd0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
27be0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
27bf0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
27c00 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
27c10 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
27c20 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
27c30 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
27c40 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
27c50 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
27c60 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
27c70 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
27c80 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
27c90 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
27ca0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
27cb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
27cc0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
27cd0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
27ce0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
27cf0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
27d00 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
27d10 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
27d20 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
27d30 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
27d40 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
27d50 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
27d60 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
27d70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
27d80 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
27d90 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
27da0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
27db0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
27dc0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
27dd0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
27de0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
27df0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
27e00 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
27e10 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
27e20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
27e30 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
27e40 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
27e50 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
27e60 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
27e70 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
27e80 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
27e90 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
27ea0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
27eb0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
27ec0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
27ed0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
27ee0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
27ef0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
27f00 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
27f10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27f20 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
27f30 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
27f40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27f50 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
27f60 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
27f70 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
27f80 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
27f90 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
27fa0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
27fb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27fc0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
27fd0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
27fe0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
27ff0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
28000 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
28010 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
28020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28030 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
28040 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
28050 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
28060 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
28070 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
28080 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
28090 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
280a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
280b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
280c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
280d0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
280e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
280f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
28100 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
28110 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
28120 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
28130 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28140 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
28150 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
28160 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
28170 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
28180 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
28190 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
281a0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
281b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
281c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
281d0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
281e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
281f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
28200 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
28210 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
28220 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
28230 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28240 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
28250 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
28260 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
28270 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
28280 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
28290 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
282a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
282b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
282c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
282d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
282e0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
282f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
28300 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
28310 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
28320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28330 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
28340 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
28350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28360 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
28370 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
28380 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
28390 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
283a0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
283b0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
283c0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
283d0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
283e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
283f0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
28400 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28410 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
28420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28430 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
28440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28450 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
28460 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
28470 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
28480 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
28490 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
284a0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
284b0 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
284c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
284d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
284e0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
284f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28500 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
28510 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
28520 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
28530 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
28540 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
28550 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
28560 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
28570 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
28580 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
28590 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
285a0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
285b0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
285c0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
285d0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
285e0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
285f0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
28600 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
28610 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
28620 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
28630 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
28640 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
28650 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
28660 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
28670 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
28680 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
28690 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
286a0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
286b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
286c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
286d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
286e0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
286f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
28700 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
28710 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
28720 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
28730 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
28740 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
28750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
28760 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
28770 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
28780 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
28790 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
287a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
287b0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
287c0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
287d0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
287e0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
287f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
28800 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
28810 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
28820 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
28830 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
28840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28850 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
28860 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
28870 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
28880 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
28890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
288a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
288b0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
288c0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
288d0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
288e0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
288f0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
28900 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
28910 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
28920 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
28930 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
28940 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
28950 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
28960 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
28970 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
28980 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
28990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
289a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
289b0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
289c0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
289d0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
289e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
289f0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
28a00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28a10 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
28a20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
28a30 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
28a40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28a50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
28a60 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
28a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28a80 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
28a90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
28aa0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
28ab0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
28ac0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
28ad0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
28ae0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
28af0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
28b00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28b10 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
28b20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
28b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28b40 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
28b50 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
28b60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
28b70 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
28b80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
28b90 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
28ba0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
28bb0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
28bc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
28bd0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
28be0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
28bf0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
28c00 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
28c10 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
28c20 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
28c30 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
28c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28c50 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
28c60 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
28c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
28c80 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
28c90 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
28ca0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
28cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28cc0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
28cd0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
28ce0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
28cf0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
28d00 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
28d10 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
28d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28d30 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
28d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
28d50 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
28d60 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
28d70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
28d80 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
28d90 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
28da0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
28db0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
28dc0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
28dd0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
28de0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
28df0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
28e00 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
28e10 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
28e20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
28e30 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
28e40 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
28e50 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
28e60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
28e70 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
28e80 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
28e90 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
28ea0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
28eb0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
28ec0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
28ed0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
28ee0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
28ef0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
28f00 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
28f10 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
28f20 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
28f30 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
28f40 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
28f50 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
28f60 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
28f70 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
28f80 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
28f90 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
28fa0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
28fb0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
28fc0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
28fd0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
28fe0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
28ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29000 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
29010 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29020 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
29030 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
29040 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
29050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
29060 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
29070 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
29080 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
29090 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
290a0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
290b0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
290c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
290d0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
290e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
290f0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
29100 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
29110 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
29120 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
29130 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
29140 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29150 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
29160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
29180 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
29190 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
291a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
291b0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
291c0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
291d0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
291e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
291f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
29200 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
29210 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
29220 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
29230 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
29240 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
29250 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
29260 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29270 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
29280 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
29290 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
292a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
292b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
292c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
292d0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
292e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
292f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
29300 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
29310 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
29320 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
29330 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
29340 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29350 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
29360 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
29370 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
29380 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
29390 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
293a0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
293b0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
293c0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
293d0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
293e0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
293f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
29400 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
29410 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
29420 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
29430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
29440 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
29450 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
29460 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
29470 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
29480 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
29490 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
294a0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
294b0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
294c0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
294d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
294e0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
294f0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
29500 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
29510 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
29520 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29530 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
29540 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
29550 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
29560 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
29570 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
29580 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
29590 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
295a0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
295b0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
295c0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
295d0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
295e0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
295f0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
29600 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
29610 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
29620 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
29630 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
29640 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
29650 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
29660 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
29670 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
29680 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
29690 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
296a0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
296b0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
296c0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
296d0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
296e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
296f0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
29700 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
29710 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
29720 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
29730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29740 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29750 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
29760 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
29770 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
29780 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
29790 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
297a0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
297b0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
297c0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
297d0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
297e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
297f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29800 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
29810 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
29820 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
29830 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
29840 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
29850 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
29860 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
29870 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
29880 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29890 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
298a0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
298b0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
298c0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
298d0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
298e0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
298f0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
29900 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
29910 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
29920 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
29930 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
29940 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
29950 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
29960 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
29970 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
29980 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
29990 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
299a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
299b0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
299c0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
299d0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
299e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
299f0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
29a00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
29a10 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
29a20 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
29a30 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
29a40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
29a50 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
29a60 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
29a70 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
29a80 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
29a90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
29aa0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
29ab0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
29ac0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
29ad0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29ae0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
29af0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
29b00 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
29b10 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
29b20 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
29b30 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
29b40 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
29b50 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
29b60 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
29b70 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
29b80 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
29b90 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
29ba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29bb0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
29bc0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
29bd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
29be0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
29bf0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
29c00 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
29c10 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
29c20 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
29c30 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
29c40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
29c50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
29c60 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
29c70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29c80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
29c90 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
29ca0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
29cb0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
29cc0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
29cd0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
29ce0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
29cf0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
29d00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
29d10 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
29d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29d30 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
29d40 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
29d50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
29d60 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
29d70 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
29d80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
29d90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
29da0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
29db0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29dc0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
29dd0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
29de0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
29df0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29e00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
29e10 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
29e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
29e30 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
29e40 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
29e50 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
29e60 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
29e70 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
29e80 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
29e90 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
29ea0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
29eb0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
29ec0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
29ed0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
29ee0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
29ef0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
29f00 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
29f10 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
29f20 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
29f30 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
29f40 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
29f50 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
29f60 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
29f70 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
29f80 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
29f90 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
29fa0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
29fb0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
29fc0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
29fd0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
29fe0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
29ff0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2a000 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2a010 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2a020 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2a030 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2a040 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2a050 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2a060 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2a070 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2a080 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2a090 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2a0a0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2a0b0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2a0c0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2a0d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2a0e0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2a0f0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2a100 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2a110 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2a120 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2a130 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2a140 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a150 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2a160 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a170 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2a180 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2a190 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2a1a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a1b0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2a1c0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2a1d0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2a1e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a1f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a200 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2a210 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2a220 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2a230 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2a240 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2a250 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2a260 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2a270 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2a280 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2a290 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2a2a0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2a2b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2a2c0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2a2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2a2e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a2f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2a300 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2a310 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2a320 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2a330 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2a340 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2a350 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2a360 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2a370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a380 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2a390 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2a3a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2a3b0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2a3c0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2a3d0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2a3e0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2a3f0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2a400 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2a410 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2a420 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2a430 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2a440 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2a450 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2a460 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2a470 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2a480 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2a490 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2a4a0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2a4b0 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2a4c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2a4d0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2a4e0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2a4f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2a500 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2a510 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2a520 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2a530 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2a540 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2a550 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2a560 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2a570 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2a580 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2a590 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2a5a0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2a5b0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2a5c0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2a5d0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2a5e0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2a5f0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2a600 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2a610 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2a620 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2a630 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2a640 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2a650 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2a660 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2a670 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a680 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2a690 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2a6a0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2a6b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a6c0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2a6d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2a6e0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2a6f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a700 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2a710 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2a720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a730 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2a740 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2a750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a760 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2a770 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2a780 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
2a790 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2a7a0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
2a7b0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2a7c0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2a7d0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2a7e0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2a7f0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2a800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2a810 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
2a820 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2a830 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2a840 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2a850 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2a860 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2a870 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2a880 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2a890 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2a8a0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2a8b0 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
2a8c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2a8d0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2a8e0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2a8f0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2a900 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2a910 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2a920 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2a930 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2a940 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2a950 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2a960 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2a970 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2a980 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2a990 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2a9a0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2a9b0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2a9c0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2a9d0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2a9e0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2a9f0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2aa00 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2aa10 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2aa20 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2aa30 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2aa40 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2aa50 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2aa60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2aa70 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2aa80 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2aa90 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2aaa0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
2aab0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2aac0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2aad0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2aae0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2aaf0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2ab00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2ab10 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2ab20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2ab30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2ab40 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ab50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2ab60 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2ab70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2ab80 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2ab90 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2aba0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
2abb0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
2abc0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
2abd0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
2abe0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2abf0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2ac00 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2ac10 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2ac20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
2ac30 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
2ac40 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2ac50 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2ac60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ac70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2ac80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2ac90 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2aca0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2acb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2acc0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2acd0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2ace0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2acf0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2ad00 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2ad10 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2ad20 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2ad30 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2ad40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2ad50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ad60 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2ad70 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2ad80 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2ad90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ada0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2adb0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2adc0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2add0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2ade0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2adf0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2ae00 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2ae10 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2ae20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ae30 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2ae40 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2ae50 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2ae60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ae70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ae80 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2ae90 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2aea0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2aeb0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2aec0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2aed0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2aee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aef0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
2af00 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
2af10 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
2af20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
2af30 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
2af40 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2af50 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2af60 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2af70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2af80 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2af90 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2afa0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2afb0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2afc0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2afd0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
2afe0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2aff0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2b000 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2b010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b020 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
2b030 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2b040 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2b050 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2b060 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2b070 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2b080 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2b090 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
2b0a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2b0b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b0c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2b0d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b0e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2b0f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2b100 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2b110 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2b120 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2b130 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2b140 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2b150 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2b160 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2b170 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
2b180 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2b190 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
2b1a0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
2b1b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
2b1c0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
2b1d0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2b1e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2b1f0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
2b200 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2b210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2b220 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2b230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b240 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
2b250 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
2b260 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2b270 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2b280 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
2b290 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
2b2a0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
2b2b0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
2b2c0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
2b2d0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
2b2e0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
2b2f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2b300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2b310 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2b320 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2b330 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2b340 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2b350 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2b360 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2b370 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
2b380 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2b390 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2b3a0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2b3b0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
2b3c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2b3d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2b3e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2b3f0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2b400 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2b410 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2b420 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
2b430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2b440 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2b450 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2b460 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2b470 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2b480 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2b490 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
2b4a0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
2b4b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b4c0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
2b4d0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2b4e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2b4f0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2b500 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
2b510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2b520 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
2b530 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b540 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2b550 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2b560 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2b570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2b580 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2b590 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2b5a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2b5b0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2b5c0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2b5d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
2b5e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2b5f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2b600 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2b610 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2b620 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b630 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b640 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2b650 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2b660 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2b670 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2b680 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b690 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
2b6a0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2b6b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2b6c0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2b6d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2b6e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
2b6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b700 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b710 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2b720 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
2b730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b740 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
2b750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2b760 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
2b770 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
2b780 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2b790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2b7a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2b7b0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
2b7c0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
2b7d0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
2b7e0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
2b7f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
2b800 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2b810 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
2b820 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
2b830 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2b840 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
2b850 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2b860 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2b870 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2b880 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2b890 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2b8a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2b8b0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
2b8c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2b8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2b8e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2b8f0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
2b900 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
2b910 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
2b920 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
2b930 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
2b940 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2b950 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2b960 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2b970 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2b980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2b990 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2b9a0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
2b9b0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
2b9c0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2b9d0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
2b9e0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
2b9f0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2ba00 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
2ba10 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
2ba20 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
2ba30 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
2ba40 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2ba50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2ba60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ba70 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2ba80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2ba90 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
2baa0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
2bab0 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
2bac0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
2bad0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
2bae0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
2baf0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2bb00 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2bb10 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2bb20 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2bb30 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2bb40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2bb50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2bb60 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
2bb70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2bb80 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2bb90 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2bba0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2bbb0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
2bbc0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2bbd0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2bbe0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
2bbf0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2bc00 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2bc10 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2bc20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
2bc30 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2bc40 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
2bc50 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
2bc60 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2bc70 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2bc80 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2bc90 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2bca0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2bcb0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2bcc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2bcd0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2bce0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2bcf0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2bd00 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2bd10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2bd20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2bd30 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2bd40 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2bd50 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2bd60 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2bd70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bd80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2bd90 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2bda0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2bdb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bdc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bdd0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2bde0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2bdf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2be00 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2be10 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2be20 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
2be30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2be40 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2be50 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2be60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
2be70 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
2be80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2be90 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2bea0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2beb0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2bec0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2bed0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2bee0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2bef0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2bf00 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
2bf10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bf20 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
2bf30 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
2bf40 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
2bf50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bf60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
2bf70 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
2bf80 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
2bf90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2bfa0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
2bfb0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
2bfc0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
2bfd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2bfe0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
2bff0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
2c000 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
2c010 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2c020 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2c030 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c040 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
2c050 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2c060 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2c070 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2c080 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2c090 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2c0a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
2c0b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2c0c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2c0d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2c0e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2c0f0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
2c100 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
2c110 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
2c120 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c130 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
2c140 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2c150 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2c160 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c170 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2c180 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2c190 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2c1a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c1b0 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
2c1c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2c1d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c1e0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
2c1f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2c200 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c210 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
2c220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2c230 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2c240 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
2c250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2c260 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2c270 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2c280 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c290 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2c2a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2c2b0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
2c2c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2c2d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2c2e0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
2c2f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2c300 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
2c310 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2c320 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c330 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
2c340 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2c350 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2c360 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2c370 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c380 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2c390 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2c3a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2c3b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2c3c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c3d0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2c3e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2c3f0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2c400 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2c410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2c420 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
2c430 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2c440 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
2c450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2c460 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2c470 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2c480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c490 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2c4a0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2c4b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
2c4c0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
2c4d0 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
2c4e0 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
2c4f0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2c500 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2c520 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
2c530 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
2c540 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2c550 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
2c560 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2c570 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2c580 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2c590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2c5a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2c5b0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2c5c0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
2c5d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
2c5e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2c5f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2c600 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
2c610 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
2c620 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
2c630 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
2c640 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
2c650 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
2c660 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
2c670 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
2c680 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
2c690 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
2c6a0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
2c6b0 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
2c6c0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2c6d0 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
2c6e0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
2c6f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2c700 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
2c710 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2c720 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
2c730 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2c740 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
2c750 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
2c760 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
2c770 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
2c780 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
2c790 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
2c7a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2c7b0 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
2c7c0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
2c7d0 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
2c7e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2c7f0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
2c800 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
2c810 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
2c820 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
2c830 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2c840 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
2c850 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2c860 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
2c870 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
2c880 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
2c890 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
2c8a0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
2c8b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2c8c0 20 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c   pArg, is a appl
2c8d0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2c8e0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
2c8f0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
2c900 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2c910 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
2c920 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2c930 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2c940 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2c950 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
2c960 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c970 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2c980 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
2c990 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
2c9a0 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
2c9b0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2c9c0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2c9d0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
2c9e0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
2c9f0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
2ca00 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
2ca10 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
2ca20 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
2ca30 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2ca40 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
2ca50 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
2ca60 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
2ca70 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
2ca80 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2ca90 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
2caa0 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
2cab0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2cac0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
2cad0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
2cae0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
2caf0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
2cb00 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
2cb10 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
2cb20 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2cb30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
2cb40 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
2cb50 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
2cb60 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2cb70 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
2cb80 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2cb90 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2cba0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
2cbb0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
2cbc0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
2cbd0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
2cbe0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
2cbf0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
2cc00 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
2cc10 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
2cc20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2cc30 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
2cc40 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2cc50 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
2cc60 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2cc70 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
2cc80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
2cc90 61 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ay return the sa
2cca0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
2ccb0 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
2ccc0 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
2ccd0 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
2cce0 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
2ccf0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
2cd00 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
2cd10 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
2cd20 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
2cd30 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
2cd40 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
2cd50 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
2cd60 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
2cd70 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
2cd80 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
2cd90 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2cda0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
2cdb0 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
2cdc0 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
2cdd0 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
2cde0 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
2cdf0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
2ce00 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
2ce10 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
2ce20 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
2ce30 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
2ce40 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
2ce50 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
2ce60 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
2ce70 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
2ce80 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
2ce90 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
2cea0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
2ceb0 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
2cec0 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
2ced0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2cee0 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
2cef0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
2cf00 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
2cf10 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
2cf20 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2cf30 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2cf40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2cf50 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2cf60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2cf70 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
2cf80 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
2cf90 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
2cfa0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2cfb0 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
2cfc0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2cfd0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2cfe0 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
2cff0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
2d000 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
2d010 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
2d020 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
2d030 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2d040 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2d050 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
2d060 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2d070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2d080 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2d090 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2d0a0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
2d0b0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
2d0c0 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
2d0d0 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
2d0e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d0f0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
2d100 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
2d110 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
2d120 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
2d130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2d140 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
2d150 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
2d160 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
2d170 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
2d180 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
2d190 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
2d1a0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2d1b0 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
2d1c0 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
2d1d0 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
2d1e0 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
2d1f0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
2d200 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
2d210 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
2d220 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
2d230 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
2d240 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
2d250 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
2d260 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
2d270 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
2d280 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
2d290 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
2d2a0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
2d2b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2d2c0 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
2d2d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2d2e0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
2d2f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2d300 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
2d310 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2d320 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2d330 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2d340 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
2d350 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2d360 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2d370 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2d380 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2d390 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d3a0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2d3b0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2d3c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2d3d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2d3e0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2d3f0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2d400 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2d410 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2d420 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
2d430 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2d440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d450 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2d460 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2d470 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
2d480 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
2d490 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
2d4a0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
2d4b0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2d4c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2d4d0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2d4e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d4f0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2d500 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2d510 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2d520 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2d530 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2d540 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2d550 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2d560 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2d570 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2d580 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2d590 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2d5a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d5b0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
2d5c0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
2d5d0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2d5e0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2d5f0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2d600 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
2d610 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2d620 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2d630 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2d640 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2d650 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2d660 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2d670 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2d680 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2d690 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2d6a0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
2d6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2d6c0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2d6d0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
2d6e0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
2d6f0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2d700 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2d710 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
2d720 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
2d730 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
2d740 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
2d750 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
2d760 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
2d770 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2d780 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2d790 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2d7a0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2d7b0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2d7c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2d7d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2d7e0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2d7f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2d800 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2d810 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d820 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2d830 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
2d840 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2d850 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2d860 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2d870 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2d880 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
2d890 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2d8a0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
2d8b0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2d8c0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2d8d0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2d8e0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
2d8f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d900 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2d910 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
2d920 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2d930 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
2d940 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2d950 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2d960 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2d970 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2d980 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d990 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2d9a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d9b0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2d9c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2d9d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d9e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2d9f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2da00 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2da10 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2da20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2da30 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2da40 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2da50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2da60 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2da70 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2da80 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2da90 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2daa0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2dab0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2dac0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
2dad0 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
2dae0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2daf0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2db00 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2db10 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2db20 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2db30 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2db40 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2db50 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2db60 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2db70 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2db80 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2db90 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2dba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2dbb0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2dbc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2dbd0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2dbe0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2dbf0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2dc00 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2dc10 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2dc20 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2dc30 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2dc40 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2dc50 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2dc60 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2dc70 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2dc80 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2dc90 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2dca0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2dcb0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2dcc0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2dcd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2dce0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2dcf0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2dd00 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2dd10 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2dd20 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2dd30 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2dd40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2dd50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2dd70 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2dd80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2dd90 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2dda0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2ddb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
2ddc0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2ddd0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
2dde0 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
2ddf0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2de00 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
2de10 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
2de20 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2de30 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2de40 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2de50 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2de60 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2de70 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2de80 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2de90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2dea0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2deb0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2dec0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2ded0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2dee0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2def0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2df00 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2df10 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2df20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2df30 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
2df40 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2df50 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2df60 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2df70 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
2df80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
2df90 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2dfa0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
2dfb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2dfc0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2dfd0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2dfe0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2dff0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2e000 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2e010 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2e020 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2e030 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2e040 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
2e050 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2e060 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
2e070 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
2e080 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
2e090 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
2e0a0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
2e0b0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
2e0c0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
2e0d0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
2e0e0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
2e0f0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2e100 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2e110 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2e120 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2e130 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2e140 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
2e150 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2e160 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2e170 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2e180 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2e190 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2e1a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2e1b0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
2e1c0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
2e1d0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
2e1e0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
2e1f0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
2e200 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
2e210 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
2e220 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2e230 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
2e240 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
2e250 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
2e260 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
2e270 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
2e280 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2e290 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2e2a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2e2b0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2e2c0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2e2d0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2e2e0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2e2f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2e300 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2e310 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2e320 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2e330 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2e340 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2e350 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2e360 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2e370 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2e380 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2e390 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2e3a0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2e3b0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2e3c0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2e3d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2e3e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e3f0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2e400 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2e410 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2e420 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2e430 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2e440 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2e450 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2e460 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2e470 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2e480 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2e490 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2e4a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2e4b0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2e4c0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2e4d0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2e4e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2e4f0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2e500 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2e510 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2e520 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2e530 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2e540 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2e550 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2e560 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2e570 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2e580 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2e590 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2e5a0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2e5b0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2e5c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2e5d0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2e5e0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2e5f0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2e600 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2e610 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2e620 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2e630 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2e640 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2e650 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2e660 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2e670 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2e680 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2e690 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2e6a0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2e6b0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2e6c0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2e6d0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2e6e0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2e6f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2e700 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2e710 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2e720 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2e730 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2e740 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2e750 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2e760 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2e770 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2e780 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2e790 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2e7a0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2e7b0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2e7c0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2e7d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2e7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2e7f0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2e800 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2e810 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2e820 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2e830 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2e840 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2e850 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2e860 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2e870 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2e880 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2e890 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2e8a0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2e8b0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2e8c0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2e8d0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2e8e0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2e8f0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2e900 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2e910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2e920 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2e930 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2e940 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2e950 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2e960 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2e970 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2e980 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2e990 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2e9a0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2e9b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2e9c0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2e9d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2e9e0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2e9f0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2ea00 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2ea10 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2ea20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2ea30 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2ea40 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2ea50 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2ea60 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2ea70 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2ea80 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2ea90 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2eaa0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2eab0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2eac0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2ead0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2eae0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2eaf0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2eb00 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2eb10 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2eb20 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2eb30 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2eb40 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2eb50 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2eb60 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2eb70 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2eb80 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2eb90 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2eba0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2ebb0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2ebc0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2ebd0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2ebe0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2ebf0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2ec00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2ec10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2ec20 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2ec30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ec40 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2ec50 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2ec60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2ec70 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2ec80 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2ec90 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2eca0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2ecb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2ecc0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2ecd0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ece0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2ecf0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2ed00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2ed10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ed20 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2ed30 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2ed40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2ed50 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2ed60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2ed70 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2ed80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ed90 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2eda0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2edb0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2edc0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2edd0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2ede0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2edf0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2ee00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2ee10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ee20 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2ee30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ee40 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2ee50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ee60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2ee70 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2ee80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2ee90 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2eea0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2eeb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2eec0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2eed0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2eee0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2eef0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2ef00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2ef10 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2ef20 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2ef30 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2ef40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ef50 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2ef60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ef70 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2ef80 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2ef90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2efa0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2efb0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2efc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2efd0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2efe0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2eff0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2f000 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2f010 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2f020 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2f030 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2f040 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2f050 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2f060 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2f070 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2f080 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2f090 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f0a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f0b0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2f0c0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2f0d0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2f0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f0f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2f100 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2f110 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2f120 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2f130 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2f140 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2f150 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2f160 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2f170 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2f180 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2f190 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2f1a0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2f1b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2f1c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f1d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2f1e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f1f0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2f200 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2f210 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2f220 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f230 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2f240 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2f250 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2f260 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2f270 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2f280 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2f290 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2f2a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2f2b0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2f2c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f2d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2f2e0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2f2f0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2f300 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2f310 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2f320 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2f330 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2f340 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2f350 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2f360 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2f370 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2f380 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2f390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2f3a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2f3b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2f3c0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2f3d0 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2f3e0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2f3f0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2f400 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2f410 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f420 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2f430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f440 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2f450 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2f460 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2f470 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
2f480 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2f490 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2f4a0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2f4b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2f4c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2f4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f4e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2f4f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2f500 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2f510 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2f520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f530 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2f540 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2f550 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2f560 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2f570 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2f580 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2f590 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2f5a0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2f5b0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2f5c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2f5d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2f5e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2f5f0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2f600 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2f610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2f620 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2f630 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2f640 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2f650 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
2f660 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
2f670 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
2f680 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2f690 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
2f6a0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
2f6b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
2f6c0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
2f6d0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
2f6e0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
2f6f0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
2f700 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
2f710 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2f720 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2f730 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2f740 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2f750 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
2f760 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
2f770 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2f780 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
2f790 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
2f7a0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
2f7b0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
2f7c0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
2f7d0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
2f7e0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
2f7f0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
2f800 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2f810 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2f820 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2f830 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2f840 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2f850 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2f860 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2f870 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2f880 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2f890 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2f8a0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2f8b0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
2f8c0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2f8d0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2f8e0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2f8f0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2f900 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2f910 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2f920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f930 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2f940 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2f950 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2f960 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2f970 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2f980 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2f990 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2f9a0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2f9b0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2f9c0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2f9d0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2f9e0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2f9f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fa00 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2fa10 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2fa20 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2fa30 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2fa40 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2fa50 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2fa60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2fa70 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2fa80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2fa90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2faa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2fab0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2fac0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2fad0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2fae0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2faf0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2fb00 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2fb10 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2fb20 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2fb30 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2fb40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fb50 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2fb60 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2fb70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2fb80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2fb90 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2fba0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2fbb0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2fbc0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2fbd0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2fbe0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2fbf0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2fc00 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2fc10 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2fc20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2fc30 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2fc40 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2fc50 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2fc60 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2fc70 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2fc80 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2fc90 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2fca0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2fcb0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2fcc0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2fcd0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2fce0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2fcf0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2fd00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2fd10 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2fd20 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2fd30 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2fd40 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2fd50 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2fd60 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2fd70 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2fd80 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2fd90 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2fda0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2fdb0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2fdc0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2fdd0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2fde0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2fdf0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2fe00 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2fe10 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2fe20 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2fe30 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2fe40 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2fe50 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2fe60 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2fe70 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2fe80 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2fe90 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2fea0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2feb0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2fec0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2fed0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2fee0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2fef0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2ff00 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2ff10 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2ff20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2ff30 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2ff40 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2ff50 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2ff60 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2ff70 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2ff80 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2ff90 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2ffa0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2ffb0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2ffc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2ffd0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2ffe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fff0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
30000 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
30010 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
30020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30030 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
30040 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
30050 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
30060 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
30070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30080 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
30090 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
300a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
300b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
300c0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
300d0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
300e0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
300f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
30100 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30110 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
30120 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
30130 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
30140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
30150 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
30160 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
30170 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
30180 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30190 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
301a0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
301b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
301c0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
301d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
301e0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
301f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30200 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
30210 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
30220 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
30230 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
30240 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30250 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
30260 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
30270 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
30280 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
30290 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
302a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
302b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
302c0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
302d0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
302e0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
302f0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
30300 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
30310 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
30320 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
30330 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
30340 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
30350 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
30360 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
30370 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
30380 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
30390 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
303a0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
303b0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
303c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
303d0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
303e0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
303f0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
30400 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
30410 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
30420 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
30430 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
30440 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
30450 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
30460 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
30470 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
30480 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
30490 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
304a0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
304b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
304c0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
304d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
304e0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
304f0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
30500 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
30510 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
30520 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
30530 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
30540 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
30550 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
30560 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
30570 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30580 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
30590 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
305a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
305b0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
305c0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
305d0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
305e0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
305f0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
30600 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
30610 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
30620 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
30630 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
30640 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
30650 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
30660 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
30670 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
30680 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
30690 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
306a0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
306b0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
306c0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
306d0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
306e0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
306f0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
30700 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
30710 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
30720 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
30730 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
30740 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
30750 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
30760 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
30770 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
30780 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
30790 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
307a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
307b0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
307c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
307d0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
307e0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
307f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30800 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
30810 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
30820 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
30830 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
30840 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
30850 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
30860 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
30870 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
30880 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
30890 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
308a0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
308b0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
308c0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
308d0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
308e0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
308f0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
30900 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
30910 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
30920 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
30930 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
30940 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
30950 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
30960 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
30970 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
30980 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
30990 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
309a0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
309b0 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
309c0 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
309d0 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
309e0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
309f0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
30a00 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
30a10 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
30a20 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
30a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
30a40 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
30a50 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
30a60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
30a70 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
30a80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30a90 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
30aa0 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
30ab0 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
30ac0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
30ad0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
30ae0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
30af0 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
30b00 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
30b10 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
30b20 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
30b30 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
30b40 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
30b50 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
30b60 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
30b70 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
30b80 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
30b90 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
30ba0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
30bb0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
30bc0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
30bd0 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
30be0 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
30bf0 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
30c00 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
30c10 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
30c20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
30c30 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
30c40 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
30c50 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
30c60 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
30c70 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
30c80 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
30c90 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
30ca0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
30cb0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
30cc0 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
30cd0 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
30ce0 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
30cf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
30d00 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
30d10 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
30d20 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
30d30 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
30d40 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
30d50 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
30d60 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
30d70 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30d80 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
30d90 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
30da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
30db0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
30dc0 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
30dd0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30de0 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
30df0 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
30e00 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
30e10 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
30e20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
30e30 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
30e40 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
30e50 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
30e60 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
30e70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
30e80 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
30e90 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
30ea0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
30eb0 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
30ec0 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
30ed0 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
30ee0 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
30ef0 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
30f00 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
30f10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
30f20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
30f30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
30f40 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
30f50 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
30f60 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
30f70 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
30f80 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
30f90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
30fa0 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
30fb0 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
30fc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
30fd0 6e 20 69 73 20 73 70 65 63 69 66 65 64 20 75 73  n is specifed us
30fe0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
30ff0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
31000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
31010 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69  HE],...)..** <li
31020 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65  > The page cache
31030 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20   allocates from 
31040 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70  its own memory p
31050 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ool supplied.** 
31060 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
31070 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
31080 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
31090 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74  E],...) rather t
310a0 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d  han.**      from
310b0 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f   the heap..** </
310c0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  ul>)^.**.** Begi
310d0 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
310e0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c  e version 3.7.3,
310f0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31100 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
31110 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
31120 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
31130 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
31140 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
31150 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  EMENT].** compil
31160 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
31170 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20   invoked.  With 
31180 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
31190 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
311a0 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  ],.** the soft h
311b0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
311c0 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d  orced on every m
311d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
311e0 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53  .  Without.** [S
311f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
31200 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
31210 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31220 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66  imit is only enf
31230 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65  orced.** when me
31240 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
31250 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
31260 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75  che.  Testing su
31270 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61  ggests that beca
31280 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20  use.** the page 
31290 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65  cache is the pre
312a0 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20  dominate memory 
312b0 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20  user in SQLite, 
312c0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
312d0 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76  ions will achiev
312e0 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20  e adequate soft 
312f0 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72  heap limit enfor
31300 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a  cement without.*
31310 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51  * the use of [SQ
31320 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
31330 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
31340 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d  **.** The circum
31350 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68  stances under wh
31360 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ich SQLite will 
31370 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74  enforce the soft
31380 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a   heap limit may.
31390 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75  ** changes in fu
313a0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
313b0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69   SQLite..*/.sqli
313c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
313d0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
313e0 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64(sqlite3_int6
313f0 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  4 N);../*.** CAP
31400 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
31410 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69  d Soft Heap Limi
31420 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44  t Interface.** D
31430 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
31440 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63  This is a deprec
31450 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  ated version of 
31460 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  the [sqlite3_sof
31470 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
31480 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
31490 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
314a0 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69   provided for hi
314b0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
314c0 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20  bility.** only. 
314d0 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61   All new applica
314e0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65  tions should use
314f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
31500 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
31510 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  64()] interface 
31520 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73  rather than this
31530 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   one..*/.SQLITE_
31540 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
31550 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
31560 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
31570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31580 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
31590 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
315a0 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
315b0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
315c0 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
315d0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
315e0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
315f0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
31600 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
31610 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
31620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31630 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
31640 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
31650 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
31660 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
31670 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
31680 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
31690 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
316a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
316b0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
316c0 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
316d0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
316e0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
316f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
31700 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
31710 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
31720 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
31730 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
31740 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
31750 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
31760 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
31770 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
31780 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
31790 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
317a0 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
317b0 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
317c0 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
317d0 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
317e0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
317f0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
31800 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
31810 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
31820 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
31830 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
31840 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
31850 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
31860 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
31870 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
31880 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
31890 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
318a0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
318b0 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
318c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
318d0 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
318e0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
318f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
31900 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
31910 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
31920 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
31930 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
31940 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
31950 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
31960 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
31970 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
31980 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
31990 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
319a0 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
319b0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
319c0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
319d0 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
319e0 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
319f0 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
31a00 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
31a10 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
31a20 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
31a30 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
31a40 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
31a50 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
31a60 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
31a70 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
31a80 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
31a90 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
31aa0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
31ab0 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
31ac0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
31ad0 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
31ae0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
31af0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
31b00 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
31b10 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
31b20 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
31b30 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
31b40 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
31b50 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
31b60 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
31b70 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
31b80 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
31b90 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
31ba0 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
31bb0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
31bc0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
31bd0 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
31be0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
31bf0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
31c00 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
31c10 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
31c20 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
31c30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
31c40 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
31c50 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
31c60 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
31c70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
31c80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
31c90 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
31ca0 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
31cb0 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
31cc0 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
31cd0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
31ce0 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
31cf0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
31d00 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
31d10 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
31d20 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
31d30 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
31d40 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
31d50 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
31d60 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
31d70 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
31d80 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
31d90 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
31da0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
31db0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
31dc0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
31dd0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
31de0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
31df0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
31e00 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
31e10 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
31e20 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
31e30 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
31e40 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
31e50 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
31e60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
31e70 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
31e80 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
31e90 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
31ea0 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
31eb0 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
31ec0 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
31ed0 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
31ee0 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
31ef0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
31f00 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
31f10 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
31f20 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
31f30 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
31f40 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
31f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31f60 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
31f70 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
31f80 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
31f90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
31fa0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
31fb0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
31fc0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
31fd0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
31fe0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
31ff0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
32000 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
32010 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
32020 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
32030 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
32040 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
32050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32060 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
32070 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
32080 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
32090 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
320a0 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
320b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
320c0 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
320d0 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
320e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
320f0 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
32100 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
32110 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
32120 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
32130 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
32140 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
32150 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
32160 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
32170 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
32180 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
32190 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
321a0 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
321b0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
321c0 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
321d0 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
321e0 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
321f0 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
32200 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
32210 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
32220 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
32230 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
32240 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
32250 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
32260 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
32270 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
32280 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
32290 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
322a0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
322b0 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
322c0 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
322d0 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
322e0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   file..**.** ^Th
322f0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
32300 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
32310 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
32320 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69   load an.** SQLi
32330 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
32340 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
32350 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
32360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74  ..**.** ^The ent
32370 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
32380 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79  c..** ^zProc may
32390 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
323a0 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
323b0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
323c0 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20  .** defaults to 
323d0 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
323e0 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68  on_init"..** ^Th
323f0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
32400 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
32410 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
32420 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
32430 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
32440 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
32450 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
32460 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  g..** ^If an err
32470 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
32480 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
32490 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71   then the.** [sq
324a0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
324b0 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
324c0 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
324d0 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72  to.** fill *pzEr
324e0 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
324f0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
32500 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
32510 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
32520 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
32530 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ]. The calling f
32540 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  unction.** shoul
32550 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
32560 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
32570 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
32580 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
32590 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
325a0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
325b0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  * [sqlite3_enabl
325c0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
325d0 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  ()] prior to cal
325e0 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a  ling this API,.*
325f0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  * otherwise an e
32600 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
32610 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
32620 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
32630 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
32640 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
32650 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
32660 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
32670 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
32680 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
32690 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
326a0 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
326b0 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
326c0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
326d0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
326e0 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
326f0 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
32700 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
32710 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
32720 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
32730 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
32740 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
32750 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
32760 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
32770 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
32780 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
32790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
327a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
327b0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
327c0 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
327d0 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
327e0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
327f0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
32800 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
32810 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
32820 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
32830 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
32840 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
32850 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
32860 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
32870 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
32880 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
32890 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
328a0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
328b0 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
328c0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
328d0 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
328e0 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45  nd off..**.** ^E
328f0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
32900 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
32910 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
32920 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74  1863..** ^Call t
32930 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
32940 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
32950 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  () routine with 
32960 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74  onoff==1.** to t
32970 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
32980 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
32990 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
329a0 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74  =0 to turn.** it
329b0 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
329c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
329d0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
329e0 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
329f0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
32a00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32a10 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
32a20 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69  ad Statically Li
32a30 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a  nked Extensions.
32a40 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
32a50 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
32a60 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66   xEntryPoint() f
32a70 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
32a80 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63  voked for.** eac
32a90 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
32aa0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
32ab0 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
32ac0 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74  e idea here is t
32ad0 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  hat.** xEntryPoi
32ae0 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72  nt() is the entr
32af0 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74  y point for a st
32b00 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
32b10 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
32b20 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62  .** that is to b
32b30 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
32b40 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20  loaded into all 
32b50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
32b60 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
32b70 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68  ^(Even though th
32b80 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f  e function proto
32b90 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20  type shows that 
32ba0 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61  xEntryPoint() ta
32bb0 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65  kes.** no argume
32bc0 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20  nts and returns 
32bd0 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76  void, SQLite inv
32be0 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74  okes xEntryPoint
32bf0 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a  () with three.**
32c00 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65   arguments and e
32c10 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67  xpects and integ
32c20 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20  er result as if 
32c30 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66  the signature of
32c40 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f   the.** entry po
32c50 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c  int where as fol
32c60 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
32c70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
32c80 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e   &nbsp;  int xEn
32c90 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62  tryPoint(.** &nb
32ca0 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a  sp;    sqlite3 *
32cb0 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  db,.** &nbsp;   
32cc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
32cd0 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70  ErrMsg,.** &nbsp
32ce0 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63  ;    const struc
32cf0 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
32d00 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a  utines *pThunk.*
32d10 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20  * &nbsp;  );.** 
32d20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
32d30 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  te>)^.**.** If t
32d40 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72  he xEntryPoint r
32d50 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72  outine encounter
32d60 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73  s an error, it s
32d70 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72  hould make *pzEr
32d80 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  rMsg.** point to
32d90 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
32da0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f  error message (o
32db0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32dc0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
32dd0 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20  ).** and return 
32de0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
32df0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53  error code].  ^S
32e00 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68  QLite ensures th
32e10 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  at *pzErrMsg.** 
32e20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63  is NULL before c
32e30 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72  alling the xEntr
32e40 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69  yPoint().  ^SQLi
32e50 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  te will invoke.*
32e60 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
32e70 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20  )] on *pzErrMsg 
32e80 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e  after xEntryPoin
32e90 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49  t() returns.  ^I
32ea0 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50  f any.** xEntryP
32eb0 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61  oint() returns a
32ec0 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71  n error, the [sq
32ed0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
32ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
32ef0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32f00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c  3_open_v2()] cal
32f10 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  l that provoked 
32f20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  the xEntryPoint(
32f30 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a  ) will fail..**.
32f40 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
32f50 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
32f60 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e  on(X) with an en
32f70 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74  try point X that
32f80 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f   is already.** o
32f90 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75  n the list of au
32fa0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
32fb0 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  ns is a harmless
32fc0 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72   no-op. ^No entr
32fd0 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20  y point.** will 
32fe0 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74  be called more t
32ff0 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  han once for eac
33000 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
33010 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70  ction that is op
33020 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ened..**.** See 
33030 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72  also: [sqlite3_r
33040 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
33050 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ion()]..*/.int s
33060 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
33070 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e  nsion(void (*xEn
33080 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29  tryPoint)(void))
33090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
330a0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
330b0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
330c0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ding.**.** ^This
330d0 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62   interface disab
330e0 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69  les all automati
330f0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65  c extensions pre
33100 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73  viously.** regis
33110 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
33120 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
33130 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  ion()]..*/.void 
33140 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
33150 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
33160 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  d);../*.** The i
33170 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
33180 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33190 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
331a0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
331b0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
331c0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
331d0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
331e0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
331f0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
33200 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
33210 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
33220 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
33230 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
33240 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
33250 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33260 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
33270 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
33280 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
33290 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
332a0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
332b0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
332c0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
332d0 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
332e0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
332f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
33300 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
33310 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33320 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
33330 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
33340 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
33350 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
33360 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
33370 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33380 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
33390 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
333a0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
333b0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
333c0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
333d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
333e0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
333f0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
33400 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
33410 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
33420 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54   module}.**.** T
33430 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
33440 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
33450 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
33460 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
33470 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
33480 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
33490 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
334a0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
334b0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
334c0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
334d0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
334e0 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
334f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
33500 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
33510 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
33520 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
33530 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
33540 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
33550 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
33560 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
33570 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33580 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
33590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
335a0 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
335b0 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
335c0 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
335d0 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
335e0 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
335f0 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
33600 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
33610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
33620 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
33630 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
33640 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
33650 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
33660 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
33670 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
33680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
33690 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
336a0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
336b0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
336c0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
336d0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
336e0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
336f0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
33700 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
33710 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
33720 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
33730 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
33740 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
33750 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
33760 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
33770 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
33780 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
33790 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
337a0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
337b0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
337c0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
337d0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
337e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
337f0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
33800 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
33810 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
33820 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
33830 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
33840 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
33850 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
33860 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
33870 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
33880 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
33890 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
338a0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
338b0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
338c0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
338d0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
338e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
338f0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
33900 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
33910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33920 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
33930 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
33940 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
33950 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33960 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
33970 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
33980 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
33990 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
339a0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
339b0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
339c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
339d0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
339e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
339f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
33a00 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
33a10 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
33a20 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
33a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
33a40 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
33a50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
33a60 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
33a70 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
33a80 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
33a90 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
33aa0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
33ab0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
33ac0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
33ad0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
33ae0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
33af0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
33b00 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
33b10 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
33b20 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
33b30 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
33b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
33b50 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
33b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33b70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33b80 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
33b90 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
33ba0 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
33bb0 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
33bc0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
33bd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
33be0 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  w);.};../*.** CA
33bf0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
33c00 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49  Table Indexing I
33c10 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45  nformation.** KE
33c20 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
33c30 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a  index_info.**.**
33c40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
33c50 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
33c60 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
33c70 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
33c80 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68  as part.** of th
33c90 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
33ca0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
33cb0 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
33cc0 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
33cd0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
33ce0 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64  om the [xBestInd
33cf0 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  ex].** method of
33d00 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
33d10 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20  e module].  The 
33d20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
33d30 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
33d40 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
33d50 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
33d60 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
33d70 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
33d80 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
33d90 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
33da0 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
33db0 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69   ^(The aConstrai
33dc0 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72  nt[] array recor
33dd0 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ds WHERE clause 
33de0 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74  constraints of t
33df0 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c  he form:.**.** <
33e00 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d  blockquote>colum
33e10 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b  n OP expr</block
33e20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  quote>.**.** whe
33e30 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
33e40 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
33e50 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68  r &gt;=.)^  ^(Th
33e60 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
33e70 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
33e80 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
33e90 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65  t[].op using one
33ea0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   of the.** [SQLI
33eb0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
33ec0 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f  INT_EQ | SQLITE_
33ed0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
33ee0 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20  _ values].)^.** 
33ef0 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74  ^(The index of t
33f00 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
33f10 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74  red in.** aConst
33f20 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
33f30 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e  )^  ^(aConstrain
33f40 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
33f50 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
33f60 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
33f70 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
33f80 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
33f90 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
33fa0 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
33fb0 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
33fc0 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a   cannot.)^.**.**
33fd0 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20   ^The optimizer 
33fe0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
33ff0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
34000 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
34010 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
34020 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
34030 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
34040 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
34050 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
34060 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
34070 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
34080 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
34090 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
340a0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68  possible..** ^Th
340b0 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
340c0 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
340d0 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
340e0 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a  terms that are.*
340f0 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68  * relevant to th
34100 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
34110 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
34120 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
34130 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f  ^Information abo
34140 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
34150 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
34160 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
34170 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66  ** ^Each term of
34180 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
34190 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
341a0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
341b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
341c0 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
341d0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
341e0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
341f0 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
34200 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
34210 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
34220 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66  to xFilter.  ^If
34230 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
34240 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
34250 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
34260 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
34270 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
34280 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
34290 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
342a0 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
342b0 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43  n argv.  ^(If aC
342c0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
342d0 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
342e0 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
342f0 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
34300 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
34310 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
34320 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
34330 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
34340 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
34350 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64  )^.**.** ^The id
34360 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
34370 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
34380 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
34390 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c  nto the.** [xFil
343a0 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20  ter] method..** 
343b0 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  ^[sqlite3_free()
343c0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ] is used to fre
343d0 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20  e idxPtr if and 
343e0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54  only if.** needT
343f0 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
34400 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rue..**.** ^The 
34410 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
34420 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
34430 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d  t from [xFilter]
34440 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63  /[xNext] will oc
34450 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f  cur in.** the co
34460 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73  rrect order to s
34470 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52  atisfy the ORDER
34480 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68   BY clause so th
34490 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a  at no separate.*
344a0 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69  * sorting step i
344b0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
344c0 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64  * ^The estimated
344d0 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e  Cost value is an
344e0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65   estimate of the
344f0 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74   cost of doing t
34500 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72  he.** particular
34510 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c   lookup.  A full
34520 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65   scan of a table
34530 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20   with N entries 
34540 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61  should have.** a
34550 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62   cost of N.  A b
34560 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20  inary search of 
34570 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74  a table of N ent
34580 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
34590 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70   a.** cost of ap
345a0 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28  proximately log(
345b0 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  N)..*/.struct sq
345c0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
345d0 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a   {.  /* Inputs *
345e0 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61  /.  int nConstra
345f0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f  int;           /
34600 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72  * Number of entr
34610 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  ies in aConstrai
34620 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  nt */.  struct s
34630 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
34640 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69  straint {.     i
34650 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
34660 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
34670 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
34680 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
34690 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  nt */.     unsig
346a0 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20  ned char op;    
346b0 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
346c0 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20  nt operator */. 
346d0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
346e0 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a  r usable;     /*
346f0 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f   True if this co
34700 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62  nstraint is usab
34710 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69  le */.     int i
34720 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20  TermOffset;     
34730 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
34740 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49  ernally - xBestI
34750 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f  ndex should igno
34760 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  re */.  } *aCons
34770 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
34780 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57     /* Table of W
34790 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
347a0 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74  traints */.  int
347b0 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
347c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
347d0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68  r of terms in th
347e0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
347f0 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  e */.  struct sq
34800 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
34810 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
34820 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
34830 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
34840 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
34850 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
34860 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
34870 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
34880 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
34890 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20   *aOrderBy;     
348a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65            /* The
348b0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
348c0 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73   */.  /* Outputs
348d0 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
348e0 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
348f0 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
34900 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
34910 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
34920 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
34930 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
34940 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
34950 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
34960 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
34970 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
34980 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
34990 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  aint */.  } *aCo
349a0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
349b0 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
349c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
349d0 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
349e0 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
349f0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
34a00 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
34a10 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
34a20 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
34a30 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
34a40 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
34a50 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
34a60 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
34a70 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
34a80 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
34a90 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
34aa0 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
34ab0 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
34ac0 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
34ad0 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
34ae0 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
34af0 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
34b00 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
34b10 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a  is index */.};..
34b20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34b30 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f  Virtual Table Co
34b40 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f  nstraint Operato
34b50 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  r Codes.**.** Th
34b60 65 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e  ese macros defin
34b70 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76  ed the allowed v
34b80 61 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  alues for the.**
34b90 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f   [sqlite3_index_
34ba0 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e  info].aConstrain
34bb0 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45  t[].op field.  E
34bc0 61 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73  ach value repres
34bd0 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61  ents.** an opera
34be0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74  tor that is part
34bf0 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   of a constraint
34c00 20 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45   term in the wHE
34c10 52 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20  RE clause of.** 
34c20 61 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65  a query that use
34c30 73 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  s a [virtual tab
34c40 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  le]..*/.#define 
34c50 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
34c60 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a  STRAINT_EQ    2.
34c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
34c80 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
34c90 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  GT    4.#define 
34ca0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
34cb0 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a  STRAINT_LE    8.
34cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
34cd0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
34ce0 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65  LT    16.#define
34cf0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
34d00 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33  NSTRAINT_GE    3
34d10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
34d20 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
34d30 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a  T_MATCH 64../*.*
34d40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
34d50 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54  ster A Virtual T
34d60 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74  able Implementat
34d70 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
34d80 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
34d90 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
34da0 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
34db0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65  ble module] name
34dc0 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d  ..** ^Module nam
34dd0 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73  es must be regis
34de0 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20  tered before.** 
34df0 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b  creating a new [
34e00 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75  virtual table] u
34e10 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20  sing the module 
34e20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67  and before using
34e30 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e   a.** preexistin
34e40 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  g [virtual table
34e50 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  ] for the module
34e60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64  ..**.** ^The mod
34e70 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69  ule name is regi
34e80 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64  stered on the [d
34e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34ea0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  on] specified.**
34eb0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
34ec0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e  rameter.  ^The n
34ed0 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
34ee0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
34ef0 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  e .** second par
34f00 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68  ameter.  ^The th
34f10 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
34f20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
34f30 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
34f40 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74  ion of the [virt
34f50 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
34f60 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68  ].   ^The fourth
34f70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
34f80 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c   an arbitrary cl
34f90 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65  ient data pointe
34fa0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
34fb0 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f   through.** into
34fc0 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61   the [xCreate] a
34fd0 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
34fe0 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72  thods of the vir
34ff0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
35000 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20  e.** when a new 
35010 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
35020 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65   be being create
35030 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a  d or reinitializ
35040 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
35060 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66  dule_v2() interf
35070 61 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20  ace has a fifth 
35080 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
35090 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
350a0 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  to a destructor 
350b0 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44  for the pClientD
350c0 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ata.  ^SQLite wi
350d0 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  ll.** invoke the
350e0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
350f0 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e  tion (if it is n
35100 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51  ot NULL) when SQ
35110 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65  Lite.** no longe
35120 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69  r needs the pCli
35130 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e  entData pointer.
35140 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
35150 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62  r will also.** b
35160 65 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  e invoked if the
35170 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35180 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
35190 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54  2() fails..** ^T
351a0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
351b0 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
351c0 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
351d0 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
351e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
351f0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
35200 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
35210 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
35220 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
35230 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
35240 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
35250 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
35260 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
35270 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
35280 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
35290 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
352a0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
352b0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
352c0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
352d0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
352e0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
352f0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
35300 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
35310 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
35320 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
35330 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
35340 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
35350 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35360 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
35370 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
35380 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
35390 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
353a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
353b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
353c0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
353d0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
353e0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
353f0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
35400 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
35410 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
35420 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
35430 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
35440 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
35450 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
35460 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
35470 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
35480 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
35490 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
354a0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
354b0 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
354c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
354d0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
354e0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
354f0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
35500 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
35510 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
35520 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
35530 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
35540 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
35550 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
35560 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
35570 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
35580 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
35590 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
355a0 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
355b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
355c0 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
355d0 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
355e0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
355f0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
35600 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
35610 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
35620 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35630 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
35640 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
35650 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
35660 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
35670 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
35680 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
35690 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
356a0 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
356b0 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
356c0 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
356d0 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
356e0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
356f0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
35700 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
35710 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
35720 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
35730 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
35740 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
35750 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
35760 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
35770 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
35780 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
35790 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
357a0 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
357b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
357c0 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
357d0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
357e0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
357f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
35800 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
35810 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
35820 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
35830 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
35840 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
35850 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
35860 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
35870 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
35880 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
35890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
358a0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
358b0 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
358c0 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
358d0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
358e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
358f0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
35900 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
35910 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
35920 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
35930 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
35940 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
35950 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
35960 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
35970 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
35980 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
35990 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
359a0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
359b0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
359c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
359d0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
359e0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
359f0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
35a00 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
35a10 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
35a20 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
35a30 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
35a40 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
35a50 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
35a60 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
35a70 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
35a80 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
35a90 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
35aa0 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
35ab0 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
35ac0 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
35ad0 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
35ae0 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
35af0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
35b00 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
35b10 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
35b20 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
35b30 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
35b40 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
35b50 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
35b60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
35b70 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
35b80 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
35b90 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
35ba0 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
35bb0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
35bc0 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
35bd0 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
35be0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
35bf0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
35c00 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
35c10 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
35c20 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
35c30 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
35c40 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
35c50 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
35c60 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
35c70 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
35c80 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
35c90 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
35ca0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
35cb0 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
35cc0 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
35cd0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
35ce0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
35cf0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
35d00 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
35d10 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
35d20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
35d30 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
35d40 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
35d50 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
35d60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
35d70 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
35d80 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
35d90 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
35da0 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
35db0 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
35dc0 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
35dd0 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
35de0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
35df0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
35e00 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
35e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
35e20 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
35e30 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
35e40 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
35e50 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
35e60 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
35e70 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
35e80 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
35e90 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
35ea0 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
35eb0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
35ec0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
35ed0 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
35ee0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
35ef0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
35f00 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
35f10 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
35f20 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
35f30 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
35f40 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
35f50 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
35f60 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
35f70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
35f80 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
35f90 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
35fa0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
35fb0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
35fc0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
35fd0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
35fe0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
35ff0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
36000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
36010 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
36020 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
36030 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
36040 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
36050 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
36060 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
36070 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
36080 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
36090 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
360a0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
360b0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
360c0 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
360d0 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
360e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
360f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
36100 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
36110 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
36120 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
36130 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
36140 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
36150 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
36160 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
36170 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
36180 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
36190 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
361a0 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
361b0 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
361c0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
361d0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
361e0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
361f0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
36200 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
36210 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
36220 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
36230 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
36240 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
36250 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
36260 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
36270 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
36280 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
36290 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
362a0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
362b0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
362c0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
362d0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
362e0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
362f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36300 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
36310 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
36320 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
36330 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
36340 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
36350 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
36360 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
36370 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
36380 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
36390 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
363a0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
363b0 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
363c0 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
363d0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
363e0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
363f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
36400 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
36410 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
36420 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
36430 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
36440 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
36450 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
36460 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
36470 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
36480 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
36490 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
364a0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
364b0 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
364c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
364d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
364e0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
364f0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
36500 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
36510 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
36520 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
36530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36540 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
36550 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
36560 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
36570 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
36580 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
36590 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
365a0 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
365b0 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
365c0 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
365d0 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
365e0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
365f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
36600 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
36610 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
36620 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
36630 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
36640 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
36650 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
36660 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
36670 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
36680 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
36690 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
366a0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
366b0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
366c0 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
366d0 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
366e0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
366f0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
36700 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
36710 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
36720 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
36730 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
36740 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
36750 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
36760 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
36770 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
36780 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
36790 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
367a0 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
367b0 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
367c0 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
367d0 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
367e0 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
367f0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
36800 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
36810 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
36820 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
36830 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
36840 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
36850 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
36860 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36870 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
36880 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
36890 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
368a0 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
368b0 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
368c0 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
368d0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
368e0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
368f0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
36900 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
36910 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
36920 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
36930 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
36940 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
36950 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
36960 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
36970 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
36980 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
36990 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
369a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
369b0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
369c0 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
369d0 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
369e0 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
369f0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
36a00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36a10 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
36a20 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
36a30 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
36a40 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
36a50 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
36a60 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
36a70 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
36a80 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
36a90 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
36aa0 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
36ab0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
36ac0 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
36ad0 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
36ae0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
36af0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
36b00 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
36b10 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
36b20 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
36b30 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
36b40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
36b50 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
36b60 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
36b70 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
36b80 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
36b90 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
36ba0 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
36bb0 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
36bc0 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
36bd0 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
36be0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
36bf0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
36c00 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
36c10 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
36c20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
36c30 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
36c40 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
36c50 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
36c60 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
36c70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
36c80 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36c90 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
36ca0 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
36cb0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
36cc0 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
36cd0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
36ce0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
36cf0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
36d00 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
36d10 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
36d20 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
36d30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
36d40 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
36d50 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
36d60 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
36d70 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
36d80 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
36d90 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
36da0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
36db0 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
36dc0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
36dd0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
36de0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
36df0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
36e00 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
36e10 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
36e20 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
36e30 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
36e40 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
36e50 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
36e60 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
36e70 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
36e80 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
36e90 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
36ea0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
36eb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
36ec0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
36ed0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
36ee0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
36ef0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
36f00 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
36f10 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
36f20 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
36f30 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
36f40 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
36f50 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
36f60 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
36f70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
36f80 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
36f90 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
36fa0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
36fb0 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
36fc0 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
36fd0 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
36fe0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
36ff0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
37000 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
37010 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
37020 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
37030 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
37040 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
37050 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
37060 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
37070 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
37080 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
37090 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
370a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
370b0 6f 76 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c  ove a BLOB Handl
370c0 65 20 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a  e to a New Row.*
370d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
370e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ion is used to m
370f0 6f 76 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ove an existing 
37100 62 6c 6f 62 20 68 61 6e 64 6c 65 20 73 6f 20 74  blob handle so t
37110 68 61 74 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a  hat it points.**
37120 20 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20   to a different 
37130 72 6f 77 20 6f 66 20 74 68 65 20 73 61 6d 65 20  row of the same 
37140 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
37150 5e 54 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20  ^The new row is 
37160 69 64 65 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79  identified.** by
37170 20 74 68 65 20 72 6f 77 69 64 20 76 61 6c 75 65   the rowid value
37180 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
37190 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20  econd argument. 
371a0 4f 6e 6c 79 20 74 68 65 20 72 6f 77 20 63 61 6e  Only the row can
371b0 20 62 65 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20   be.** changed. 
371c0 5e 54 68 65 20 64 61 74 61 62 61 73 65 2c 20 74  ^The database, t
371d0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
371e0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 62 6c 6f  on which the blo
371f0 62 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  b handle is open
37200 0a 2a 2a 20 72 65 6d 61 69 6e 20 74 68 65 20 73  .** remain the s
37210 61 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65  ame. Moving an e
37220 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e  xisting blob han
37230 64 6c 65 20 74 6f 20 61 20 6e 65 77 20 72 6f 77  dle to a new row
37240 20 63 61 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65   can be.** faste
37250 72 20 74 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74  r than closing t
37260 68 65 20 65 78 69 73 74 69 6e 67 20 68 61 6e 64  he existing hand
37270 6c 65 20 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61  le and opening a
37280 20 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20   new one..**.** 
37290 5e 28 54 68 65 20 6e 65 77 20 72 6f 77 20 6d 75  ^(The new row mu
372a0 73 74 20 6d 65 65 74 20 74 68 65 20 73 61 6d 65  st meet the same
372b0 20 63 72 69 74 65 72 69 61 20 61 73 20 66 6f 72   criteria as for
372c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
372d0 70 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d  pen()] -.** it m
372e0 75 73 74 20 65 78 69 73 74 20 61 6e 64 20 74 68  ust exist and th
372f0 65 72 65 20 6d 75 73 74 20 62 65 20 65 69 74 68  ere must be eith
37300 65 72 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78  er a blob or tex
37310 74 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 69  t value stored i
37320 6e 0a 2a 2a 20 74 68 65 20 6e 6f 6d 69 6e 61 74  n.** the nominat
37330 65 64 20 63 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66  ed column.)^ ^If
37340 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20   the new row is 
37350 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 6e 20 74  not present in t
37360 68 65 20 74 61 62 6c 65 2c 20 6f 72 20 69 66 0a  he table, or if.
37370 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 63  ** it does not c
37380 6f 6e 74 61 69 6e 20 61 20 62 6c 6f 62 20 6f 72  ontain a blob or
37390 20 74 65 78 74 20 76 61 6c 75 65 2c 20 6f 72 20   text value, or 
373a0 69 66 20 61 6e 6f 74 68 65 72 20 65 72 72 6f 72  if another error
373b0 20 6f 63 63 75 72 73 2c 20 61 6e 0a 2a 2a 20 53   occurs, an.** S
373c0 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65  QLite error code
373d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
373e0 20 74 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65   the blob handle
373f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 61   is considered a
37400 62 6f 72 74 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20  borted..** ^All 
37410 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
37420 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
37430 62 5f 72 65 61 64 28 29 5d 2c 20 5b 73 71 6c 69  b_read()], [sqli
37440 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
37450 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
37460 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 29 5d 20  _blob_reopen()] 
37470 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64 20 62 6c  on an aborted bl
37480 6f 62 20 68 61 6e 64 6c 65 20 69 6d 6d 65 64 69  ob handle immedi
37490 61 74 65 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20  ately return.** 
374a0 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a  SQLITE_ABORT..**
374b0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
374c0 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
374d0 62 61 73 65 20 68 61 6e 64 6c 65 20 65 72 72 6f  base handle erro
374e0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
374f0 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ge..*/.SQLITE_EX
37500 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
37510 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70  qlite3_blob_reop
37520 65 6e 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  en(sqlite3_blob 
37530 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37550 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42  EF: Close A BLOB
37560 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43   Handle.**.** ^C
37570 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
37580 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
37590 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c  ** ^Closing a BL
375a0 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  OB shall cause t
375b0 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
375c0 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74  action to commit
375d0 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65  .** if there are
375e0 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c   no other BLOBs,
375f0 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70   no pending prep
37600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c  ared statements,
37610 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61   and the.** data
37620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37630 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69  is in [autocommi
37640 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20  t mode]..** ^If 
37650 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20  any writes were 
37660 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42  made to the BLOB
37670 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20  , they might be 
37680 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a  held in cache.**
37690 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65   until the close
376a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68   operation if th
376b0 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a  ey will fit..**.
376c0 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65  ** ^(Closing the
376d0 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63   BLOB often forc
376e0 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a  es the changes.*
376f0 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e  * out to disk an
37700 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20  d so if any I/O 
37710 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68  errors occur, th
37720 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f  ey will likely o
37730 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74  ccur.** at the t
37740 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f  ime when the BLO
37750 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e  B is closed.  An
37760 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
37770 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
37780 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
37790 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
377a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e   return value.)^
377b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f  .**.** ^(The BLO
377c0 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f  B is closed unco
377d0 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76  nditionally.  Ev
377e0 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69  en if this routi
377f0 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ne returns.** an
37800 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65   error code, the
37810 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63   BLOB is still c
37820 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  losed.)^.**.** ^
37830 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
37840 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
37850 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61   pointer (such a
37860 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72  s would be retur
37870 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c  ned.** by a fail
37880 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ed call to [sqli
37890 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
378a0 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
378b0 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71  no-op..*/.int sq
378c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
378d0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
378e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
378f0 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  F: Return The Si
37900 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
37910 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  OB.**.** ^Return
37920 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79  s the size in by
37930 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
37940 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74  accessible via t
37950 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  he .** successfu
37960 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42  lly opened [BLOB
37970 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20   handle] in its 
37980 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20  only argument.  
37990 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e  ^The.** incremen
379a0 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75  tal blob I/O rou
379b0 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72  tines can only r
379c0 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69  ead or overwriti
379d0 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62  ng existing.** b
379e0 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65  lob content; the
379f0 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  y cannot change 
37a00 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
37a10 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ob..**.** This r
37a20 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
37a30 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
37a40 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
37a50 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
37a60 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
37a70 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
37a80 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
37a90 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
37aa0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
37ab0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
37ac0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
37ad0 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
37ae0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
37af0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
37b00 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
37b10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
37b20 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
37b30 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73  havior..*/.int s
37b40 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
37b50 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
37b60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37b70 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
37b80 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
37b90 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28  entally.**.** ^(
37ba0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
37bb0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
37bc0 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
37bd0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
37be0 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
37bf0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
37c00 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
37c10 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
37c20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
37c30 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
37c40 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
37c50 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a  et iOffset.)^.**
37c60 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
37c70 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
37c80 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
37c90 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
37ca0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
37cb0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
37cc0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
37cd0 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20  is read.  ^If N 
37ce0 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a  or iOffset is.**
37cf0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
37d00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
37d10 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
37d20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
37d30 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  .** ^The size of
37d40 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68   the blob (and h
37d50 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
37d60 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
37d70 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
37d80 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
37d90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
37da0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
37db0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
37dc0 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
37dd0 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20  from an expired 
37de0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
37df0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
37e00 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
37e10 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
37e20 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
37e30 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
37e40 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
37e50 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
37e60 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20  wise, an [error 
37e70 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74  code] or an [ext
37e80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
37e90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
37ea0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37eb0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
37ec0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
37ed0 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
37ee0 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
37ef0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
37f00 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
37f10 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
37f20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
37f30 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
37f40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
37f50 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
37f60 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
37f70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
37f80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
37f90 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
37fa0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
37fb0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
37fc0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
37fd0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
37fe0 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a  ob_write()]..*/.
37ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
38000 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c  _read(sqlite3_bl
38010 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69  ob *, void *Z, i
38020 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt N, int iOffse
38030 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38040 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20  REF: Write Data 
38050 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72  Into A BLOB Incr
38060 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20  ementally.**.** 
38070 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  ^This function i
38080 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20  s used to write 
38090 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65  data into an ope
380a0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
380b0 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  from a.** caller
380c0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
380d0 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61  . ^N bytes of da
380e0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
380f0 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a  om the buffer Z.
38100 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e  ** into the open
38110 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20   BLOB, starting 
38120 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
38130 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
38140 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
38150 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
38160 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
38170 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
38180 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
38190 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
381a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
381b0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
381c0 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
381d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
381e0 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
381f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
38200 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
38210 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
38220 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
38230 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
38240 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
38250 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
38260 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
38270 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74  I..** ^If offset
38280 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
38290 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
382a0 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
382b0 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
382c0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
382d0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
382e0 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e  a is written.  ^
382f0 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  If N is.** less 
38300 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54  than zero [SQLIT
38310 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
38320 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
38330 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20   is written..** 
38340 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
38350 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20  BLOB (and hence 
38360 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
38370 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
38380 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
38390 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
383a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
383b0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
383c0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
383d0 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61  pt to write to a
383e0 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
383f0 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
38400 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
38410 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
38420 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20  BORT].  ^Writes 
38430 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74  to the BLOB that
38440 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66   occurred.** bef
38450 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61  ore the [BLOB ha
38460 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72  ndle] expired ar
38470 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63  e not rolled bac
38480 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69  k by the.** expi
38490 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61  ration of the ha
384a0 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20  ndle, though of 
384b0 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61  course those cha
384c0 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61  nges might.** ha
384d0 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74  ve been overwrit
384e0 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65  ten by the state
384f0 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65  ment that expire
38500 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  d the BLOB handl
38510 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72  e.** or by other
38520 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61   independent sta
38530 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
38540 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c  (On success, sql
38550 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
38560 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
38570 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
38580 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f  e, an  [error co
38590 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
385a0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
385b0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
385c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
385d0 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
385e0 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
385f0 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
38600 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
38610 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
38620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38630 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
38640 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
38650 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
38660 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
38670 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
38680 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
38690 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
386a0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
386b0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
386c0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
386d0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
386e0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
386f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
38700 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _read()]..*/.int
38710 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
38720 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ite(sqlite3_blob
38730 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   *, const void *
38740 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f  z, int n, int iO
38750 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
38760 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
38770 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a   File System Obj
38780 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ects.**.** A vir
38790 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
387a0 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
387b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
387c0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
387d0 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
387e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
387f0 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
38800 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
38810 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
38820 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
38830 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
38840 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
38850 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
38860 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
38870 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
38880 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
38890 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
388a0 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
388b0 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
388c0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
388d0 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
388e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
388f0 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66  fs_find() interf
38900 61 63 65 20 72 65 74