/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 8f18e4931c32e971b850fd6a469ecb56affdcbb1:


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 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
8580: 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ll guarantee tha
8590: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
85a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
85b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
85c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
85d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
85e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
85f0: 61 74 68 6e 61 6d 65 28 29 2e 20 20 5e 53 51 4c  athname().  ^SQL
8600: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
8610: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
8620: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
8630: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
8640: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
8650: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
8660: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
8670: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8680: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
8690: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
86a0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
86b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
86c0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
86d0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
86e0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
86f0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8700: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8710: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8720: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
8730: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
8740: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
8750: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
8760: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
8770: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
8780: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
8790: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
87a0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
87b0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
87c0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
87d0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
87e0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
87f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8800: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
8810: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8820: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
8830: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
8840: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
8850: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8860: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
8870: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8880: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8890: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
88a0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
88b0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
88c0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
88d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
88e0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
88f0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
8900: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
8910: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
8920: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
8930: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
8940: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8950: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
8960: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
8970: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
8980: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
8990: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
89a0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
89b0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
89c0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
89d0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
89e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
89f0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
8a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
8a10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8a20: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8a30: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
8a40: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8a50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8a60: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
8a70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8a80: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8a90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8aa0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8ab0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8ac0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
8ad0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8ae0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8af0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8b00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
8b10: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
8b20: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
8b30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
8b40: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
8b50: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
8b60: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
8b70: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
8b80: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
8b90: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
8ba0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
8bb0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
8bc0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
8bd0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
8be0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
8bf0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
8c00: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
8c10: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
8c20: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
8c30: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
8c40: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
8c50: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
8c60: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
8c70: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
8c80: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
8c90: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
8ca0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
8cb0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
8cc0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
8cd0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
8ce0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
8cf0: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
8d00: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
8d10: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
8d20: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
8d30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
8d40: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
8d50: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8d60: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8d70: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
8d80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8d90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8da0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
8db0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
8dc0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
8dd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
8de0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8df0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
8e00: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8e10: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8e20: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8e30: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
8e40: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8e50: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8e60: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8e70: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
8e80: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
8e90: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
8ea0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
8eb0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
8ec0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8ed0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
8ee0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
8ef0: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
8f00: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
8f20: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
8f30: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
8f40: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
8f50: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
8f60: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
8f70: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
8f80: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
8f90: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8fa0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
8fb0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
8fc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
8fd0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
8fe0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
8ff0: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
9000: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
9010: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
9020: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
9030: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
9040: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
9050: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9060: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
9070: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
9080: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
9090: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
90a0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
90b0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
90c0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
90d0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
90e0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
90f0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
9100: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
9110: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
9120: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
9130: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
9140: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
9150: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
9160: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
9170: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
9180: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
9190: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
91a0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
91b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
91c0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
91d0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
91e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
91f0: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
9200: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
9210: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
9220: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
9230: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
9240: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
9250: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
9260: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
9270: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
9280: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
9290: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
92a0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
92b0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
92c0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n call..**.** ^T
92d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
92e0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
92f0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
9300: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
9310: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
9320: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
9330: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
9340: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
9350: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
9360: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
9370: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9380: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
9390: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
93a0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
93b0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
93c0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
93d0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
93e0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
93f0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
9400: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
9410: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
9420: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
9430: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
9440: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
9450: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
9460: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
9470: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9480: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
9490: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
94a0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
94b0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
94c0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
94d0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
94e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
94f0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
9500: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
9510: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
9520: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
9530: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
9540: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
9550: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
9560: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
9570: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
9580: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
9590: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
95a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
95b0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
95c0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
95d0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
95e0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
95f0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9600: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
9610: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
9620: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
9630: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
9640: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
9650: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
9660: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
9680: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
9690: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
96a0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
96b0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
96c0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
96d0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
96e0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
96f0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
9700: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
9710: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
9720: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
9730: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
9740: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
9750: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
9760: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
9770: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
9780: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
9790: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
97a0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
97b0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
97c0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
97d0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
97e0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
97f0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
9800: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
9810: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
9820: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
9830: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
9840: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
9850: 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36 34  multipled by 864
9860: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
9870: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
9880: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
9890: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
98a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
98b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
98c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
98d0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
98e0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
98f0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
9900: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
9910: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
9920: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
9930: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
9940: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
9950: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
9960: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
9970: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
9980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
9990: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
99a0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
99b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99c0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
99d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99e0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
99f0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
9a00: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
9a10: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
9a20: 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e  ently 2) */.  in
9a30: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
9a40: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
9a50: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
9a60: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
9a70: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
9a80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
9a90: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
9aa0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
9ab0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
9ac0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
9ad0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
9ae0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
9af0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
9b00: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
9b10: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
9b20: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
9b30: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
9b40: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
9b50: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
9b60: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9b70: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9b80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9b90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9ba0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9bb0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9bc0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9bd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9be0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9bf0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c00: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
9c10: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
9c20: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
9c30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c40: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
9c50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
9c60: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9c70: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9c80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9c90: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9ca0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9cb0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9cc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9cd0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9ce0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9cf0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9d00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
9d10: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
9d20: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
9d30: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
9d40: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
9d50: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
9d60: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
9d70: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
9d80: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
9d90: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
9da0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9db0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9dc0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9dd0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9de0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9df0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9e00: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
9e10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
9e20: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
9e30: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
9e40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9e50: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
9e60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
9e70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
9e80: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
9e90: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9ea0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
9eb0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
9ec0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
9ed0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
9ee0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
9ef0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
9f00: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
9f10: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
9f20: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
9f30: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9f40: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
9f50: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
9f60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9f70: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
9f80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9f90: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
9fa0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
9fb0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
9fc0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
9fd0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
9fe0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
9ff0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a000: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
a010: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
a020: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a030: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
a040: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
a050: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
a060: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
a070: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
a080: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
a090: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
a0a0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
a0b0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
a0c0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
a0d0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
a0e0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
a0f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
a100: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
a110: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
a120: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
a130: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
a140: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
a150: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
a160: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a170: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a180: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
a190: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
a1a0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
a1b0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
a1c0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
a1d0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
a1e0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
a1f0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
a200: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
a210: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
a220: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a230: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
a240: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
a250: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
a260: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
a270: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
a280: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
a290: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
a2a0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
a2b0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
a2c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a2d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a2e0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a2f0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
a300: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
a310: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
a320: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
a330: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
a340: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
a350: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
a360: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
a370: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
a380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a390: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
a3a0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
a3c0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
a3d0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
a3e0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
a3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a400: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
a410: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
a420: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
a430: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
a440: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
a450: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
a460: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
a470: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
a480: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
a490: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
a4a0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
a4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
a4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a4d0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
a4e0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
a4f0: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
a500: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
a510: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
a520: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
a530: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
a540: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
a550: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a560: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a570: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
a580: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
a590: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
a5a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a5b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
a5c0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
a5d0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
a5e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a5f0: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
a600: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
a610: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
a620: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
a630: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
a640: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
a650: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
a660: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
a670: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
a680: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
a690: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
a6a0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
a6b0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
a6c0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
a6d0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
a6e0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
a6f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
a700: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
a710: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
a720: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
a730: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
a740: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
a750: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
a760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
a770: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
a780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a790: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
a7a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7b0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
a7c0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
a7d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
a7e0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
a7f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
a800: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
a810: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
a820: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
a830: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
a840: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
a850: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
a860: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
a870: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
a880: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
a890: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
a8a0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
a8b0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
a8c0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
a8d0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
a8e0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
a8f0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
a900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a910: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
a920: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
a930: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
a940: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
a950: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
a960: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
a970: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
a980: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
a990: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
a9a0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
a9b0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a9c0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
a9d0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
a9e0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
a9f0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
aa00: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
aa10: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
aa20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
aa30: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
aa40: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
aa50: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
aa60: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
aa70: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
aa80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
aa90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
aaa0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
aab0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
aac0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
aad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aae0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
aaf0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
ab00: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
ab10: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
ab20: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ab30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ab40: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
ab50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
ab60: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ab70: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ab80: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
ab90: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
aba0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
abb0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
abc0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
abd0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
abe0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
abf0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
ac00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
ac10: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
ac20: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ac30: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
ac40: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
ac50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
ac60: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
ac70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ac80: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
ac90: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
aca0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
acb0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
acc0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
acd0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
ace0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
acf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
ad00: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ad10: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
ad20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ad30: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
ad40: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
ad50: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
ad60: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
ad70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
ad80: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
ad90: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
ada0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
adb0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
adc0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
add0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
ade0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
adf0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
ae00: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
ae10: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
ae20: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
ae30: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
ae40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
ae50: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
ae60: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ae70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ae80: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ae90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
aea0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
aeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
aec0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
aed0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
aee0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
aef0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
af10: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
af20: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
af30: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
af40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
af50: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
af60: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
af70: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
af80: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
af90: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
afa0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
afb0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
afc0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
afd0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
afe0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
aff0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
b000: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
b010: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
b020: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
b030: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
b040: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
b050: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
b060: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
b070: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
b080: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
b090: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b0a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
b0b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
b0c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
b0d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
b0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
b0f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
b100: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
b110: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
b120: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
b130: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
b140: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
b150: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
b160: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
b170: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
b180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b190: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
b1a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
b1b0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
b1c0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
b1d0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
b1e0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
b1f0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
b200: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
b210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
b220: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
b230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
b240: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
b250: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
b260: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b270: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
b280: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
b290: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
b2a0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
b2b0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
b2c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
b2d0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
b2e0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
b2f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
b300: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
b310: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
b320: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
b330: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
b340: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
b350: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
b360: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
b370: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b380: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
b390: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
b3a0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
b3b0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
b3c0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
b3d0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
b3e0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
b3f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b400: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
b410: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
b420: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
b430: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
b440: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
b450: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b460: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
b470: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
b480: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
b490: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
b4a0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
b4b0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
b4c0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
b4d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
b4e0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
b4f0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
b500: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
b510: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
b520: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
b530: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
b540: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
b550: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
b560: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
b570: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
b580: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
b590: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
b5a0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b5b0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
b5c0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
b5d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
b5e0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b5f0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
b600: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
b610: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
b620: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
b630: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
b640: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
b650: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
b660: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
b670: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
b680: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
b690: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b6a0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
b6b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
b6c0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
b6d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
b6e0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
b6f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
b700: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
b710: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
b720: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
b730: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
b740: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
b750: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
b760: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
b770: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
b780: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
b790: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
b7a0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
b7b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
b7c0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
b7d0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
b7e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b7f0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
b800: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
b810: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
b820: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
b830: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
b840: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
b850: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
b860: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b870: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
b880: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
b890: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
b8a0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
b8b0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
b8c0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
b8d0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
b8e0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
b8f0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
b900: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
b910: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b920: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
b930: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
b940: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
b950: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
b960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b970: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
b980: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
b990: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b9a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
b9b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
b9c0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
b9d0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
b9e0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
b9f0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
ba00: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
ba10: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
ba20: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ba30: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
ba40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
ba50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
ba60: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
ba70: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
ba80: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
ba90: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
baa0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
bab0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
bac0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
bad0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
bae0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
baf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bb00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
bb10: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
bb20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
bb30: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
bb40: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
bb50: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
bb60: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
bb70: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
bb80: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
bb90: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
bba0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
bbb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bbc0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
bbd0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
bbe0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
bbf0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
bc00: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
bc10: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
bc20: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
bc30: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bc40: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
bc50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
bc60: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
bc70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bc80: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
bc90: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
bca0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
bcb0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
bcc0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
bcd0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
bce0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bcf0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
bd00: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
bd10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bd20: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
bd30: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
bd40: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
bd50: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
bd60: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
bd70: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
bd80: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
bd90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
bda0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
bdb0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
bdc0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
bdd0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
bde0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
bdf0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
be00: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
be10: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
be20: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
be30: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
be40: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
be50: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
be60: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
be70: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
be80: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
be90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bea0: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
beb0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
bec0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
bed0: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
bee0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
bef0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
bf00: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
bf10: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
bf20: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
bf30: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
bf40: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
bf50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
bf60: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
bf70: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf80: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
bf90: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
bfa0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
bfb0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
bfc0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
bfd0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
bfe0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
bff0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c000: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
c010: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
c020: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
c030: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
c040: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
c050: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
c060: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
c070: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
c080: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
c090: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
c0a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
c0b0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
c0c0: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
c0d0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
c0e0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
c0f0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c100: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
c110: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c120: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
c130: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
c140: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
c150: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
c160: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
c170: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
c180: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
c190: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
c1a0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
c1b0: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
c1c0: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
c1d0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
c1e0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
c200: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
c210: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
c220: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
c230: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
c240: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c250: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
c260: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
c270: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
c280: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
c290: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
c2a0: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
c2b0: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
c2c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
c2d0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
c2e0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
c2f0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
c300: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
c310: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
c320: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
c330: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
c340: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
c350: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
c360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
c370: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
c380: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
c390: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c3a0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
c3b0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
c3c0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
c3d0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
c3e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c3f0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
c400: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
c410: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
c420: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
c430: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
c440: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
c450: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
c460: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
c470: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
c480: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
c490: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
c4a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c4b0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
c4c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
c4d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
c4e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
c4f0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
c500: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c510: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
c520: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
c530: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
c540: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c550: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
c560: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
c570: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
c580: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
c590: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
c5a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c5b0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
c5c0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
c5d0: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
c5e0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
c5f0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
c600: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
c610: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
c620: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
c630: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
c640: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
c650: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
c660: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
c670: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
c680: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
c690: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
c6a0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
c6b0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
c6c0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c6d0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
c6e0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
c6f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
c700: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
c710: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
c720: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c730: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
c740: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
c750: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
c760: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
c770: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
c780: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
c790: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
c7a0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
c7b0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
c7c0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
c7d0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
c7e0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
c7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
c800: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
c810: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
c820: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
c830: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
c840: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
c850: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
c860: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
c870: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
c880: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
c890: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
c8a0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
c8b0: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
c8c0: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
c8d0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
c8e0: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
c8f0: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
c900: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
c910: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
c920: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
c930: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
c940: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
c950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
c960: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
c970: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
c980: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
c990: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
c9a0: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
c9b0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
c9c0: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
c9d0: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
c9e0: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
c9f0: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
ca00: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
ca10: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
ca20: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
ca30: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
ca40: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
ca50: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
ca60: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
ca70: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
ca80: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
ca90: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
caa0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
cab0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cac0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
cad0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
cae0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
caf0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
cb00: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
cb10: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
cb20: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
cb30: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
cb40: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
cb50: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
cb60: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cb70: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
cb80: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
cb90: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
cba0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
cbb0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
cbc0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
cbd0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
cbe0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
cbf0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
cc00: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
cc10: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
cc20: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
cc30: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
cc40: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
cc50: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
cc60: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
cc70: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
cc80: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
cc90: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
cca0: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
ccb0: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
ccc0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
ccd0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
cce0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
ccf0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
cd00: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
cd10: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
cd20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cd30: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
cd40: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
cd50: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
cd60: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cd70: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
cd80: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
cd90: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
cda0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
cdb0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
cdc0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
cdd0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
cde0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cdf0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
ce00: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
ce10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ce20: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
ce30: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
ce40: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
ce50: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
ce60: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
ce70: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
ce80: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
ce90: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
cea0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
ceb0: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
cec0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
ced0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
cee0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
cef0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
cf00: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
cf10: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
cf20: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
cf30: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
cf40: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cf50: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
cf60: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
cf70: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
cf80: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
cf90: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
cfa0: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
cfb0: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
cfc0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
cfd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
cfe0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
cff0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
d000: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
d010: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
d020: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d030: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
d040: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
d050: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
d060: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
d070: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
d080: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
d090: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
d0a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
d0b0: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
d0c0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
d0d0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
d0e0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
d0f0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
d100: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
d110: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
d120: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
d130: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
d140: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
d150: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
d160: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
d170: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
d180: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
d190: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d1a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
d1c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
d1d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
d1f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
d200: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
d210: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
d220: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
d230: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
d240: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
d250: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
d260: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
d270: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
d280: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
d290: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
d2a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
d2b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
d2c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
d2d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
d2e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
d2f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
d300: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
d310: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
d320: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
d330: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
d340: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
d350: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
d360: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
d370: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
d380: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
d390: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
d3a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
d3b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
d3c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
d3d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
d3e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
d3f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
d400: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
d410: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
d420: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
d430: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
d440: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
d450: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
d460: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
d470: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
d480: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
d490: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
d4a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
d4b0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
d4c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d4d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
d4e0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
d4f0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
d500: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
d510: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
d520: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
d530: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d540: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
d550: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
d560: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
d570: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
d580: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
d590: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d5a0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
d5b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
d5c0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
d5d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d5e0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
d5f0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
d600: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
d610: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
d620: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
d630: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
d640: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
d650: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
d660: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
d670: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
d680: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
d690: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
d6a0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
d6b0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
d6c0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
d6d0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d6e0: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
d6f0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
d700: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
d710: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
d720: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
d730: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
d740: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
d750: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
d760: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
d770: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d780: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d790: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d7a0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d7b0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d7c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d7d0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d7e0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
d7f0: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
d800: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
d810: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
d820: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
d830: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
d840: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d850: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
d860: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
d870: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
d880: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d890: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
d8a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d8b0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d8c0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d8d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
d8e0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
d8f0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
d900: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
d910: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
d920: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
d930: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
d940: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
d950: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d960: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
d970: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
d980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d990: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d9a0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d9b0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
d9c0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
d9d0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
d9e0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
d9f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
da10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
da20: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
da30: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
da40: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
da50: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
da60: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
da70: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
da80: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
da90: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
daa0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
dab0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
dac0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
dad0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
dae0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
daf0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
db00: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
db10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
db20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
db30: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
db40: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
db50: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
db60: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
db70: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
db80: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
db90: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
dba0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
dbb0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
dbc0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
dbd0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
dbe0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
dbf0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
dc00: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
dc10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dc20: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
dc30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
dc40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
dc50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
dc60: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
dc70: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
dc80: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
dc90: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
dca0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
dcb0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
dcc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
dcd0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
dce0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
dcf0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
dd00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
dd10: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
dd20: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
dd30: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
dd40: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
dd50: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
dd60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
dd70: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
dd80: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
dd90: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dda0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
ddb0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
ddc0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
ddd0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dde0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ddf0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
de00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
de10: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
de20: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
de30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
de40: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
de50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
de60: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
de70: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
de80: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
de90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dea0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
deb0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dec0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ded0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dee0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
def0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
df00: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
df10: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
df20: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
df30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
df40: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
df50: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
df60: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
df70: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
df80: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
df90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dfa0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
dfb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dfc0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
dfd0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
dfe0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
dff0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
e000: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
e010: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
e020: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
e030: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
e040: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
e050: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
e060: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
e070: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
e080: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e090: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
e0a0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
e0b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e0c0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
e0d0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
e0e0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
e0f0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
e100: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
e110: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
e120: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
e130: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
e140: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
e150: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e160: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
e170: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e180: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
e190: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
e1a0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e1b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e1c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e1d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e1e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
e1f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e200: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
e210: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
e220: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
e230: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
e240: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
e250: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
e260: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
e270: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
e280: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
e2a0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
e2b0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
e2c0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
e2d0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
e2e0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
e2f0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
e300: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
e310: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
e320: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
e330: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
e340: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e350: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
e360: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e370: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
e380: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
e390: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
e3a0: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
e3b0: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
e3c0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
e3d0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
e3e0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
e3f0: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
e400: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
e410: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
e420: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
e430: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
e440: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
e450: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
e460: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
e470: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
e480: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e490: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
e4a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e4b0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
e4c0: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
e4e0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
e4f0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e500: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
e510: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
e520: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
e530: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
e540: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
e550: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
e560: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
e570: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
e580: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
e590: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
e5a0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
e5b0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
e5c0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
e5d0: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
e5e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e5f0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
e600: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e610: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e620: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e630: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e640: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
e650: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
e660: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
e670: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
e680: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
e690: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
e6a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
e6b0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
e6c0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
e6d0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
e6e0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
e6f0: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
e700: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
e710: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
e720: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
e730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
e740: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
e750: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e760: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
e770: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
e780: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e790: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
e7a0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
e7b0: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
e7c0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e7d0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
e7e0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
e7f0: 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
e800: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
e810: 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
e820: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
e830: 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
e840: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
e850: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
e860: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e870: 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
e880: 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
e890: 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
e8a0: 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
e8b0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
e8c0: 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
e8d0: 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
e8e0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
e8f0: 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
e900: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
e910: 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
e920: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
e930: 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
e940: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
e950: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e960: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
e970: 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
e980: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e990: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
e9a0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e9b0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e9c0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e9d0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e9e0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e9f0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
ea00: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
ea10: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
ea20: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61   cache implemena
ea30: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
ea40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
ea50: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
ea60: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
ea70: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
ea80: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
ea90: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
eaa0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
eab0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
eac0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
ead0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
eae0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
eaf0: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
eb00: 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
eb10: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
eb20: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
eb30: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
eb40: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
eb50: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
eb60: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
eb70: 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
eb80: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
eb90: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
eba0: 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
ebb0: 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
ebc0: 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
ebd0: 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
ebe0: 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
ebf0: 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
ec00: 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
ec10: 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
ec20: 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
ec30: 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
ec40: 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
ec50: 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
ec60: 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
ec70: 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
ec80: 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
ec90: 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
eca0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
ecb0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
ecc0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
ecd0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
ece0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
ecf0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
ed00: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
ed10: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
ed20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ed30: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
ed40: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
ed50: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
ed60: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
ed70: 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
ed80: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
ed90: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
eda0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
edb0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
edc0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
edd0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
ede0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
edf0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
ee00: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
ee10: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
ee20: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
ee30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ee40: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
ee50: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
ee60: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
ee70: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
ee80: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
ee90: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
eea0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
eeb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
eec0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
eed0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
eee0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
eef0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
ef00: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
ef10: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
ef20: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
ef30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
ef40: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
ef50: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
ef60: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
ef70: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
ef80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ef90: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
efa0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
efb0: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
efc0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
efd0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
efe0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
eff0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
f000: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
f010: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
f020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
f030: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
f040: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
f050: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
f060: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
f070: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
f080: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
f090: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f0a0: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
f0b0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
f0c0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
f0d0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
f0e0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
f0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f100: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
f110: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
f120: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
f130: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
f140: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
f150: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
f160: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
f170: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
f180: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
f190: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f1a0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
f1b0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
f1c0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
f1d0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
f1e0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
f1f0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f200: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
f210: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
f220: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
f230: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
f240: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
f250: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
f260: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
f270: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f280: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
f290: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f2a0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f2b0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f2c0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f2d0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
f2e0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
f2f0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f300: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
f310: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
f320: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
f330: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
f340: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
f350: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
f360: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
f370: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
f380: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
f390: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
f3a0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
f3b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
f3c0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f3d0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
f3e0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
f3f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f400: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
f410: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f420: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f430: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f440: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f450: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f460: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f470: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
f480: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
f490: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
f4a0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
f4b0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
f4c0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4d0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
f4e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f4f0: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
f500: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
f510: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
f520: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
f530: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f540: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
f550: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f560: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f570: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f580: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f590: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f5a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f5b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
f5c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
f5d0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
f5e0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f5f0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
f600: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
f610: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
f620: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
f630: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
f640: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
f650: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
f660: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
f670: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
f680: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
f690: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
f6a0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
f6b0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
f6c0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
f6d0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
f6e0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
f6f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f700: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f710: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f720: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f730: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f740: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f750: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
f760: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
f770: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
f780: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
f790: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
f7a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7b0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f7c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f7e0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
f7f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
f800: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
f810: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f820: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f830: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f840: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
f850: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
f860: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
f870: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
f880: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
f890: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
f8a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
f8b0: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
f8c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f8d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f8e0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
f8f0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
f900: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
f910: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
f920: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
f930: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
f940: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
f950: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
f960: 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
f970: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
f980: 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
f990: 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
f9a0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f9b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
f9c0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
f9d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
f9e0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
f9f0: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
fa00: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
fa10: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
fa20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
fa30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fa40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
fa50: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
fa60: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
fa70: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
fa80: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
fa90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
faa0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
fab0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
fac0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
fad0: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
fae0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
faf0: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
fb00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
fb10: 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
fb20: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
fb30: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
fb40: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
fb50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
fb60: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
fb70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
fb80: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
fb90: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
fba0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fbb0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fbc0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
fbd0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fbe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
fbf0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
fc00: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
fc10: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
fc20: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
fc30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
fc40: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
fc50: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
fc60: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc70: 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
fc80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
fc90: 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
fca0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
fcb0: 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
fcc0: 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
fcd0: 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
fce0: 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
fcf0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
fd00: 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
fd10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
fd20: 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
fd30: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fd40: 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
fd50: 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
fd60: 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
fd70: 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
fd80: 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
fd90: 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
fda0: 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
fdb0: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
fdc0: 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
fdd0: 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
fde0: 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
fdf0: 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
fe00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fe10: 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
fe20: 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
fe30: 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
fe40: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
fe50: 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
fe60: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
fe70: 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
fe80: 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
fe90: 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
fea0: 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
feb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fec0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
fed0: 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
fee0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
ff00: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
ff10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
ff20: 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
ff30: 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
ff40: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
ff50: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
ff60: 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
ff70: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
ff80: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
ff90: 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
ffa0: 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
ffb0: 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
ffc0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
ffd0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
ffe0: 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
fff0: 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
10000 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
10010 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
10020 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
10030 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
10040 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
10050 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10060 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
10070 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
10080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10090 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
100a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
100b0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
100c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
100d0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
100e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
100f0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
10100 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10120 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
10130 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10150 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
10160 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10180 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
10190 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
101a0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
101b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
101c0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
101d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
101e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
101f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10200 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
10210 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
10220 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
10230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10240 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
10250 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
10260 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10280 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
10290 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
102a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
102b0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
102c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
102d0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
102e0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
102f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10300 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
10310 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
10320 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10340 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
10350 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
10360 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
10370 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
10380 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
10390 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
103a0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
103b0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
103c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
103d0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
103e0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
103f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10400 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
10410 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
10420 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
10430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10440 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
10450 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
10460 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10470 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10490 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
104a0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
104b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
104c0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
104d0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
104e0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
104f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10500 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10510 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10530 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
10550 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
10570 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10580 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
10590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
105a0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
105b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
105c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
105d0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
105e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
105f0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10600 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10610 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10620 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10630 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10640 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10650 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10660 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10670 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
10680 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10690 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
106a0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
106b0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
106c0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
106d0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
106e0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
106f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10700 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10710 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
10720 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10730 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
10740 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10750 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
10760 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
10770 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10780 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
10790 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
107a0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
107b0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
107c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
107d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
107e0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
107f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10800 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
10810 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
10820 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
10830 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
10840 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
10850 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
10860 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10870 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
10880 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10890 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
108a0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
108b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
108c0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
108d0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
108e0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
108f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10900 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
10910 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
10920 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
10930 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10940 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
10950 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
10960 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10970 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
10980 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
10990 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
109a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
109b0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
109c0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
109d0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
109e0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
109f0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
10a00 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
10a10 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10a20 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
10a30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
10a40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
10a50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10a60 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
10a70 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
10a80 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
10a90 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
10aa0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
10ab0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
10ac0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
10ad0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
10ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
10af0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
10b00 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
10b10 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
10b20 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
10b30 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
10b40 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
10b50 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
10b60 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
10b70 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
10b80 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
10b90 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
10ba0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
10bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10bc0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
10bd0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
10be0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
10bf0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
10c00 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
10c10 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
10c20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
10c30 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
10c40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
10c50 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
10c60 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
10c70 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
10c80 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
10c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
10ca0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
10cb0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
10cc0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a   int int */.../*
10cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
10ce0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
10cf0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
10d00 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
10d10 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
10d20 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
10d30 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
10d40 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
10d50 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10d60 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
10d70 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
10d80 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
10d90 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
10da0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
10db0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
10dc0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
10dd0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
10de0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
10df0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
10e00 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
10e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
10e20 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
10e30 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
10e40 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
10e50 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
10e60 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
10e70 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
10e80 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
10e90 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
10ea0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
10eb0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
10ec0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
10ed0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
10ee0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
10ef0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
10f00 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
10f10 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
10f20 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
10f30 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
10f40 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
10f50 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
10f60 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
10f70 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
10f80 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
10f90 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
10fa0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
10fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
10fc0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
10fd0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
10fe0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
10ff0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
11000 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
11010 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
11020 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11030 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11040 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
11050 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
11060 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
11070 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
11080 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
11090 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
110a0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
110b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
110c0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
110d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
110e0 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
110f0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
11100 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
11110 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
11120 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
11130 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
11140 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
11150 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
11160 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
11170 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11180 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
11190 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
111a0 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
111b0 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
111c0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
111d0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
111e0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
111f0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
11200 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
11210 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
11220 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
11230 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
11240 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11250 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
11260 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
11270 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
11280 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
11290 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
112a0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
112b0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
112c0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
112d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
112e0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
112f0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
11300 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
11310 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
11320 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
11330 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
11340 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
11350 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
11360 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
11370 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
11380 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
11390 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
113a0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
113b0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
113c0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
113d0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
113e0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
113f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
11400 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
11410 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
11420 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
11430 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
11440 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
11450 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
11460 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
11470 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
11480 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
11490 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
114a0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
114b0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
114c0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
114d0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
114e0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
114f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
11500 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
11510 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
11520 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
11530 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
11540 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
11550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
11560 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11570 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
11580 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
11590 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
115a0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
115b0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
115c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
115d0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
115e0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
115f0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
11600 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
11610 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
11620 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
11630 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
11640 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
11650 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
11660 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
11670 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
11680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11690 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
116a0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
116b0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
116c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
116d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
116e0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
116f0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
11700 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
11710 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
11720 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
11730 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
11740 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
11750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11760 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
11770 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
11780 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
11790 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
117a0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
117b0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
117c0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
117d0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
117e0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
117f0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
11800 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
11810 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
11820 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
11830 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
11840 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
11850 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
11860 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
11870 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
11880 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
11890 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
118a0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
118b0 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
118c0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
118d0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
118e0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
118f0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
11900 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
11910 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11920 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
11930 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
11940 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
11950 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
11960 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
11970 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
11980 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
11990 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
119a0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
119b0 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
119c0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
119d0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
119e0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
119f0 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
11a00 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
11a10 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
11a20 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
11a30 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
11a40 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
11a50 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
11a60 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
11a70 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
11a80 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
11a90 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
11aa0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
11ab0 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
11ac0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
11ad0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
11ae0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
11af0 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
11b00 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
11b10 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
11b20 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
11b30 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
11b40 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
11b50 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
11b60 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
11b70 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
11b80 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
11b90 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
11ba0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
11bb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11bc0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
11bd0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
11be0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
11bf0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
11c00 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
11c10 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
11c20 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
11c30 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
11c40 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
11c50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
11c60 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
11c70 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
11c80 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
11c90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
11ca0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11cb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
11cc0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
11cd0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
11ce0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
11cf0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
11d00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11d10 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
11d20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
11d30 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
11d40 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
11d50 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
11d60 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11d70 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
11d80 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
11d90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
11da0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11db0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
11dc0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
11dd0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
11de0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
11df0 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
11e00 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
11e10 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
11e20 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
11e30 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
11e40 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
11e50 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
11e60 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11e70 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
11e80 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
11e90 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
11ea0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
11eb0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
11ec0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
11ed0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
11ee0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
11ef0 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
11f00 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
11f10 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
11f20 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
11f30 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
11f40 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
11f50 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11f60 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
11f70 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
11f80 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
11f90 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
11fa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
11fb0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
11fc0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
11fd0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
11fe0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
11ff0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
12000 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
12010 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
12020 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
12030 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
12040 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
12050 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
12060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
12070 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
12080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12090 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
120a0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
120b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
120c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
120d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
120e0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
120f0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
12100 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
12110 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
12120 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
12130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
12140 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
12150 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
12160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
12170 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
12180 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
12190 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
121a0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
121b0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
121c0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
121d0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
121e0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
121f0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
12200 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
12210 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
12220 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
12230 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
12240 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
12250 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
12260 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
12270 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
12280 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
12290 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
122a0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
122b0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
122c0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
122d0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
122e0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
122f0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
12300 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
12310 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
12320 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
12330 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
12340 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
12350 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
12360 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
12370 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
12380 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
12390 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
123a0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
123b0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
123c0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
123d0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
123e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
123f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
12400 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
12410 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
12420 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
12430 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
12440 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
12450 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
12460 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
12470 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12480 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12490 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
124a0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
124b0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
124c0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
124d0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
124e0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
124f0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
12500 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
12510 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
12520 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
12530 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
12540 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
12550 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
12560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
12570 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
12580 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
12590 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
125a0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
125b0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
125c0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
125d0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
125e0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
125f0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
12600 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
12610 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
12620 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
12630 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
12640 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
12650 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
12660 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
12670 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
12680 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
12690 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
126a0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
126b0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
126c0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
126d0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
126e0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
126f0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
12700 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
12710 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
12720 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
12730 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
12740 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
12750 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
12760 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12770 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
12780 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
12790 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
127a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
127b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
127c0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
127d0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
127e0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
127f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
12800 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12810 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
12820 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
12830 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
12840 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
12850 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
12860 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
12870 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
12880 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
12890 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
128a0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
128b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
128c0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
128d0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
128e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
128f0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
12900 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
12910 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
12920 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
12930 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
12940 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
12950 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
12960 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
12970 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
12980 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
12990 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
129a0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
129b0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
129c0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
129d0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
129e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
129f0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
12a00 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
12a10 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
12a20 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
12a30 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
12a40 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
12a50 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
12a60 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
12a70 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
12a80 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
12a90 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
12aa0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
12ab0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
12ac0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12ad0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
12ae0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12af0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12b00 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
12b10 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
12b20 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
12b30 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
12b40 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
12b50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
12b60 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
12b70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12b80 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
12b90 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
12ba0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
12bb0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
12bc0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
12bd0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
12be0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
12bf0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
12c00 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
12c10 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
12c20 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
12c30 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
12c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
12c50 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
12c60 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
12c70 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
12c80 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
12c90 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
12ca0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
12cb0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
12cc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
12cd0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
12ce0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
12cf0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
12d00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12d10 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
12d20 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
12d30 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
12d40 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
12d50 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
12d60 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
12d70 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
12d80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
12d90 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
12da0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
12db0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
12dc0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
12dd0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
12de0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
12df0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12e00 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
12e10 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
12e20 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
12e30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
12e40 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
12e50 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
12e60 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
12e70 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
12e80 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
12e90 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
12ea0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
12eb0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
12ec0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
12ed0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
12ee0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
12ef0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
12f00 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
12f10 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
12f20 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
12f30 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
12f40 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
12f50 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
12f60 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
12f70 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
12f80 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
12f90 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
12fa0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
12fb0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
12fc0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
12fd0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
12fe0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
12ff0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
13000 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
13010 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13020 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
13030 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
13040 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
13050 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13060 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
13070 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
13080 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
13090 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
130a0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
130b0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
130c0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
130d0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
130e0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
130f0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
13100 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
13110 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
13120 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
13130 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
13140 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
13150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13160 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
13170 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
13180 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
13190 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
131a0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
131b0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
131c0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
131d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
131e0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
131f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13200 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
13210 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
13220 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
13230 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
13240 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
13250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
13260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
13270 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
13280 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
13290 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
132a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
132b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
132c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
132d0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
132e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
132f0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
13300 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
13310 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
13320 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
13330 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
13340 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13350 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
13360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13370 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
13380 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
13390 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
133a0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
133b0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
133c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
133d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
133e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
133f0 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
13400 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
13410 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
13420 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
13430 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
13440 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
13450 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
13460 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
13470 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
13480 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
13490 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
134a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
134b0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
134c0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
134d0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
134e0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
134f0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
13500 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
13510 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
13520 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13530 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
13540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
13550 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13560 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
13570 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
13580 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
13590 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
135a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
135b0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
135c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
135d0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
135e0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
135f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13600 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
13610 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
13620 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
13630 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
13640 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
13650 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
13660 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
13670 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
13680 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
13690 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
136a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
136b0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
136c0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
136d0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
136e0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
136f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
13700 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
13710 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
13720 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
13730 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
13740 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
13750 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
13760 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
13770 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
13780 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
13790 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
137a0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
137b0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
137c0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
137d0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
137e0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
137f0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
13800 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
13810 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
13820 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
13830 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
13840 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
13850 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
13860 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13870 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
13880 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
13890 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
138a0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
138b0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
138c0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
138d0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
138e0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
138f0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
13900 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
13910 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
13920 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
13930 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
13940 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
13950 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
13960 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
13970 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
13980 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
13990 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
139a0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
139b0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
139c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
139d0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
139e0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
139f0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
13a00 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
13a10 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
13a20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
13a30 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
13a40 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
13a50 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
13a60 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
13a70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
13a80 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
13a90 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
13aa0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
13ab0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
13ac0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
13ad0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
13ae0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
13af0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
13b00 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
13b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
13b20 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
13b30 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
13b40 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
13b50 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
13b60 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
13b70 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
13b80 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
13b90 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
13ba0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
13bb0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
13bc0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
13bd0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
13be0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
13bf0 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
13c00 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
13c10 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
13c20 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
13c30 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
13c40 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
13c50 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
13c60 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
13c70 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
13c80 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
13c90 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
13ca0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
13cb0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
13cc0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
13cd0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
13ce0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
13cf0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
13d00 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
13d10 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
13d20 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
13d30 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
13d40 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
13d50 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
13d60 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13d70 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13d80 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13d90 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13da0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13db0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
13dc0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
13dd0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
13de0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
13df0 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
13e00 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
13e10 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
13e20 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
13e30 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
13e40 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
13e50 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13e60 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
13e70 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
13e80 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
13e90 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
13ea0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
13eb0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
13ec0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13ed0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
13ee0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
13ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
13f00 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
13f10 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
13f20 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
13f30 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
13f40 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
13f50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
13f60 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
13f70 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
13f80 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
13f90 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
13fa0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
13fb0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
13fc0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
13fd0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
13fe0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
13ff0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
14000 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
14010 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
14020 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
14030 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
14040 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
14050 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
14060 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
14070 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14080 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
14090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
140a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
140b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
140c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
140d0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
140e0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
140f0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
14100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14110 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
14120 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
14130 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
14140 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
14150 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
14160 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
14170 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
14180 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
14190 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
141a0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
141b0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
141c0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
141d0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
141e0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
141f0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14200 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
14210 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
14220 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
14230 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
14240 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
14250 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
14260 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
14270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
14280 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
14290 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
142a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
142b0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
142c0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
142d0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
142e0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
142f0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
14300 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
14310 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
14320 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
14330 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
14340 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
14350 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
14360 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
14370 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
14380 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
14390 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
143a0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
143b0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
143c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
143d0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
143e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
143f0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
14400 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
14410 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
14420 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
14430 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
14440 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
14450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14460 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
14470 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
14480 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44   Queries.**.** D
14490 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
144a0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
144b0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
144c0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
144d0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
144e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
144f0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14500 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14510 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14520 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14530 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14540 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14550 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
14560 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
14570 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
14580 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
14590 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
145a0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
145b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
145c0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
145d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
145e0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
145f0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14610 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14620 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14630 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14640 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14650 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
14660 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
14670 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
14680 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
14690 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
146a0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
146b0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
146c0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
146d0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
146e0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
146f0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14700 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14710 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14720 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14730 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14740 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14750 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
14760 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
14770 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
14780 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
14790 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
147a0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
147b0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
147c0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
147d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
147e0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
147f0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14800 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14810 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14820 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14830 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14840 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14850 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
14860 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
14870 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
14880 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
14890 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
148a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
148b0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
148c0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
148d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
148e0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
148f0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
14900 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
14910 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14920 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
14930 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
14940 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
14950 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
14960 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
14970 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
14980 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
14990 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
149a0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
149b0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
149c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
149d0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
149e0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
149f0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
14a00 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
14a10 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
14a20 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
14a30 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
14a40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
14a50 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
14a60 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
14a70 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
14a80 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
14a90 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
14aa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
14ab0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14ac0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
14ad0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
14ae0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
14af0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
14b00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
14b10 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
14b20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14b30 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
14b40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14b50 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
14b60 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14b70 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
14b80 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
14b90 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
14ba0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
14bb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14bc0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
14bd0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14be0 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  >.**.** ^The sql
14bf0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14c00 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
14c10 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
14c20 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
14c30 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
14c40 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
14c50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14c60 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
14c70 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
14c80 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
14c90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
14ca0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
14cb0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
14cc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
14cd0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
14ce0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
14cf0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
14d00 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
14d10 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
14d20 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20   it should pass 
14d30 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
14d40 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
14d50 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14d60 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
14d70 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14d80 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
14d90 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
14da0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
14db0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14dc0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
14dd0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
14de0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
14df0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
14e00 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
14e10 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
14e20 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
14e30 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
14e40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
14e50 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
14e60 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
14e70 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
14e80 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
14e90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14ea0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14eb0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14ec0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14ed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14ee0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14ef0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14f00 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14f10 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14f20 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14f30 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14f40 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14f50 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14f60 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14f70 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14f80 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14f90 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14fa0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14fb0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14fc0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14fd0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14fe0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14ff0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
15000 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
15010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
15020 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
15030 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15040 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
15050 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
15060 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
15070 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
15080 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
15090 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
150a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
150b0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
150c0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
150d0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
150e0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
150f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
15100 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
15110 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
15120 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
15130 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
15140 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
15150 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
15160 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
15170 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
15180 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
15190 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
151a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
151b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
151c0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
151d0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
151e0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
151f0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
15200 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
15210 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
15220 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
15230 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
15240 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
15250 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
15260 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
15270 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
15280 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
15290 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
152a0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
152b0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
152c0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
152d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
152e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
152f0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
15300 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
15310 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
15320 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
15330 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
15340 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15350 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
15360 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
15370 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
15380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15390 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
153a0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
153b0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
153c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
153d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ring..**.** ^(In
153e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
153f0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
15400 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
15410 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
15420 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
15430 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
15440 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
15450 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
15460 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
15470 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15480 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
15490 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
154a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
154b0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
154c0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
154d0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
154e0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
154f0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
15500 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
15510 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
15520 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
15530 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
15540 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
15550 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
15560 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
15570 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
15580 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
15590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
155a0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
155b0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
155c0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
155d0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
155e0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
155f0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
15600 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
15610 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
15620 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
15630 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
15640 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
15650 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
15660 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
15670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
15680 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15690 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
156a0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
156b0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
156c0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
156d0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
156e0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
156f0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
15700 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
15710 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
15720 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
15730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
15740 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
15750 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
15760 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
15770 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
15780 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
15790 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
157a0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
157b0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
157c0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
157d0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
157e0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
157f0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
15800 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
15810 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
15820 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
15830 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
15840 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
15850 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
15860 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
15870 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
15880 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
15890 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
158a0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
158b0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
158c0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
158d0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
158e0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
158f0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
15900 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
15910 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
15920 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
15930 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
15940 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
15950 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
15960 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
15970 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
15980 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
15990 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
159a0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
159b0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
159c0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
159d0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
159e0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
159f0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
15a00 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
15a10 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
15a20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
15a30 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
15a40 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
15a50 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
15a60 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
15a70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15a80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15a90 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
15aa0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
15ab0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15ac0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
15ad0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
15ae0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
15af0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
15b00 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15b10 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15b20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
15b30 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
15b40 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
15b50 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
15b60 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
15b70 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
15b80 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
15b90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
15ba0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
15bb0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15bc0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
15bd0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
15be0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
15bf0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
15c00 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
15c10 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
15c20 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
15c30 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15c40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15c50 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
15c60 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
15c70 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
15c80 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
15c90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
15ca0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
15cb0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
15cc0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
15cd0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
15ce0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
15cf0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
15d00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15d10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
15d20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
15d30 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
15d40 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
15d50 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
15d60 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
15d70 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
15d80 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
15d90 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
15da0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
15db0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
15dc0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
15dd0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
15de0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
15df0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
15e00 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
15e10 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
15e20 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
15e30 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
15e40 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
15e50 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
15e60 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
15e70 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
15e80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
15e90 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
15ea0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
15eb0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
15ec0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
15ed0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
15ee0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
15ef0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
15f00 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
15f10 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
15f20 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15f30 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
15f40 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
15f50 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
15f60 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
15f70 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
15f80 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
15f90 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
15fa0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
15fb0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
15fc0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15fd0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
15fe0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
15ff0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
16000 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
16010 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
16020 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
16030 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
16040 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
16050 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
16060 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
16070 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
16080 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
16090 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
160a0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
160b0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
160c0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
160d0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
160e0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
160f0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
16100 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
16110 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
16120 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16130 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
16140 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
16150 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
16160 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
16170 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
16180 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
16190 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
161a0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
161b0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
161c0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
161d0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
161e0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
161f0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
16200 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
16210 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
16220 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
16230 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
16240 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
16250 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
16260 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
16270 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
16280 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16290 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
162a0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
162b0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
162c0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
162d0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
162e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
162f0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
16300 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16310 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
16320 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
16330 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
16340 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
16350 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
16360 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
16370 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
16380 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
16390 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
163a0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
163b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
163c0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
163d0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
163e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
163f0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
16400 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
16410 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
16420 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16430 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
16440 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
16450 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
16460 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
16470 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
16480 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
16490 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
164a0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
164b0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
164c0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
164d0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
164e0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
164f0 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
16500 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
16510 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
16520 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
16530 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
16540 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
16550 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
16560 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
16570 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
16580 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
16590 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
165a0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
165b0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
165c0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
165d0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
165e0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
165f0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
16600 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
16610 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
16620 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
16630 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
16640 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
16650 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
16660 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
16670 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
16680 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
16690 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
166a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
166b0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
166c0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
166d0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
166e0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
166f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
16700 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
16710 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16720 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
16730 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
16740 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
16750 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
16760 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
16770 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
16780 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
16790 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
167a0 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
167b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
167c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
167d0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
167e0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
167f0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
16800 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
16810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
16820 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
16830 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16840 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
16850 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
16860 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16870 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
16880 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
16890 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
168a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
168b0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
168c0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
168d0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
168e0 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
168f0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16900 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16910 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
16920 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16930 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16940 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
16950 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
16960 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
16970 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
16980 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
16990 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
169a0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
169b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
169c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
169d0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
169e0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
169f0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16a00 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
16a10 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
16a20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
16a30 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16a40 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
16a50 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16a60 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
16a70 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
16a80 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
16a90 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
16aa0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
16ab0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
16ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
16ad0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
16ae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
16af0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
16b00 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
16b10 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
16b20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
16b30 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  boundary..**.** 
16b40 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
16b50 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
16b60 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
16b70 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
16b80 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
16b90 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
16ba0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
16bb0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
16bc0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
16bd0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
16be0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
16bf0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
16c00 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
16c10 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
16c20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
16c30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
16c40 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
16c50 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
16c60 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
16c70 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
16c80 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
16c90 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
16ca0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
16cb0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
16cc0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
16cd0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
16ce0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
16cf0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
16d00 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
16d10 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
16d20 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
16d30 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
16d40 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
16d50 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
16d60 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
16d70 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
16d80 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
16d90 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
16da0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
16db0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
16dc0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
16dd0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
16de0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
16df0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
16e00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16e10 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
16e20 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
16e30 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
16e40 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
16e50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
16e60 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16e70 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16e80 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
16e90 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
16ea0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
16eb0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
16ec0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
16ed0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
16ee0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
16ef0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
16f00 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
16f10 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
16f20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
16f30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
16f40 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
16f50 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
16f60 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
16f70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
16f80 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
16f90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
16fa0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16fb0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
16fc0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
16fd0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
16fe0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
16ff0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
17000 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
17010 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
17020 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
17030 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
17040 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
17050 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17060 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
17070 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
17080 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
17090 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
170a0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
170b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
170c0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
170d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
170e0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
170f0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
17100 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
17110 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
17120 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
17130 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17140 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
17150 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
17160 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
17170 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
17180 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
17190 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
171a0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
171b0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
171c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
171d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
171e0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
171f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
17200 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
17210 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
17220 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
17230 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
17240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
17250 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17260 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
17270 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
17280 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
17290 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
172a0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
172b0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
172c0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
172d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
172e0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
172f0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
17300 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
17310 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
17320 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
17330 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
17340 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
17350 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
17360 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
17370 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
17380 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17390 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
173a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
173b0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
173c0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
173d0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
173e0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
173f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
17400 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
17410 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
17420 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
17430 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
17440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17450 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
17460 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
17470 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
17480 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
17490 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
174a0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
174b0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
174c0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
174d0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
174e0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
174f0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
17500 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
17510 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
17520 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
17530 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
17540 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
17550 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
17560 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
17570 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
17580 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
17590 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
175a0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
175b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
175c0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
175d0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
175e0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
175f0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
17600 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
17610 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
17620 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
17630 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
17640 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
17650 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
17660 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
17670 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
17680 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
17690 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
176a0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
176b0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
176c0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
176d0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
176e0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
176f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
17700 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
17710 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
17720 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
17730 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
17740 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
17750 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
17760 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
17770 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
17780 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
17790 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
177a0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
177b0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
177c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
177d0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
177e0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
177f0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
17800 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
17810 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
17820 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
17830 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17850 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
17860 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17870 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
17880 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17890 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
178a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
178b0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
178c0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
178d0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
178e0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
178f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17900 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
17910 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
17920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17930 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
17940 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
17950 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
17960 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
17970 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
17980 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
17990 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
179a0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
179b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
179c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
179d0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
179e0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
179f0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
17a00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17a10 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
17a20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
17a30 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
17a40 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
17a50 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
17a60 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
17a70 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
17a80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17a90 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
17aa0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
17ab0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
17ac0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
17ad0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
17ae0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
17af0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
17b00 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
17b10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17b20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
17b30 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17b40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17b50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
17b60 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
17b70 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
17b80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17b90 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
17ba0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
17bb0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
17bc0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
17bd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
17be0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
17bf0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17c00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17c10 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
17c20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
17c30 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
17c40 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
17c50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
17c60 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
17c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17c80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
17c90 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
17ca0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
17cb0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
17cc0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
17cd0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
17ce0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
17cf0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
17d00 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
17d10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
17d20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
17d30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
17d40 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
17d50 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
17d60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
17d70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
17d80 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
17d90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
17da0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
17db0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
17dc0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
17dd0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
17de0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
17df0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
17e00 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
17e10 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
17e20 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
17e30 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
17e40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
17e50 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
17e60 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
17e70 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
17e80 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
17e90 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
17ea0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
17eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
17ec0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
17ed0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
17ee0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
17ef0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
17f00 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
17f10 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
17f20 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
17f30 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
17f40 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
17f50 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
17f60 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
17f70 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
17f80 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
17f90 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
17fa0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
17fb0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
17fc0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
17fd0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
17fe0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
17ff0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
18000 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
18010 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
18020 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
18030 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
18040 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
18050 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
18060 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
18070 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
18080 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
18090 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
180a0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
180b0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
180c0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
180d0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
180e0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
180f0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
18100 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
18110 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
18120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
18130 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
18140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
18150 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
18160 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
18170 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
18180 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
18190 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
181a0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
181b0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
181c0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
181d0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
181e0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
181f0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
18200 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
18210 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
18220 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
18230 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
18240 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
18250 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
18260 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
18270 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
18280 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
18290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
182a0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
182b0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
182c0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
182d0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
182e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
182f0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
18300 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
18310 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
18320 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
18330 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
18340 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
18350 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
18360 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
18370 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
18380 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
18390 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
183a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
183b0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
183c0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
183d0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
183e0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
183f0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
18400 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
18410 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
18420 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
18430 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
18440 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
18450 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
18460 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
18470 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
18480 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
18490 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
184a0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
184b0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
184c0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
184d0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
184e0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
184f0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
18500 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
18510 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
18520 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
18530 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
18540 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
18550 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
18560 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
18570 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
18580 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
18590 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
185a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
185b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
185c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
185d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
185e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
185f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
18600 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18610 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
18620 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18630 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
18640 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
18650 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
18660 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18670 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
18680 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
18690 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
186a0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
186b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
186c0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
186d0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
186e0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
186f0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
18700 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
18710 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
18720 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
18730 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
18740 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
18750 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
18760 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
18770 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
18780 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18790 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
187a0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
187b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
187c0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
187d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
187e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
187f0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
18800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18810 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
18820 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
18830 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
18840 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
18850 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
18860 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
18870 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
18880 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
18890 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
188a0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
188b0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
188c0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
188d0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
188e0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
188f0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
18900 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
18910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18920 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
18930 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
18940 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
18950 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18960 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
18970 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
18980 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
18990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
189a0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
189b0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
189c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
189d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
189e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
189f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
18a00 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
18a10 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
18a20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
18a30 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
18a40 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
18a50 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
18a60 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
18a70 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
18a80 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
18a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18aa0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18ab0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
18ac0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
18ad0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
18ae0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
18af0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
18b00 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
18b10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
18b20 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
18b30 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
18b40 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
18b50 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
18b60 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
18b70 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
18b80 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
18b90 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
18ba0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
18bb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18bc0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
18bd0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
18be0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18bf0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
18c00 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
18c10 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
18c20 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
18c30 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
18c40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18c50 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
18c60 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
18c70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
18c80 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
18c90 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
18ca0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
18cb0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
18cc0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
18cd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18ce0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
18cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
18d00 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
18d10 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
18d20 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
18d30 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
18d40 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
18d50 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
18d60 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
18d70 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
18d80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
18d90 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
18da0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
18db0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
18dc0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
18dd0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
18de0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
18df0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
18e00 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
18e10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18e20 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
18e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
18e40 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
18e50 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
18e60 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
18e70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
18e80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18e90 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
18ea0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
18eb0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
18ec0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
18ed0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18ee0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
18ef0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18f00 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18f10 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
18f20 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
18f30 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
18f40 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
18f50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18f60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
18f70 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
18f80 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
18f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18fa0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
18fb0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
18fc0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18fd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18ff0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
19000 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
19010 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19020 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19040 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
19050 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
19060 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
19070 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19080 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19090 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
190a0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
190b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
190c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
190d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
190e0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
190f0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
19100 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19110 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19120 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19130 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
19140 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
19150 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19160 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19170 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19180 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
19190 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
191a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
191b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
191c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
191d0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
191e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
191f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19200 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19210 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
19220 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
19230 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19240 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19250 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19260 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
19270 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
19280 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19290 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
192a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
192b0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
192c0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
192d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
192e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
192f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19300 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
19310 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
19320 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19330 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19340 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19350 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
19360 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
19370 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19380 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19390 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
193a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
193b0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
193c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
193d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
193e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
193f0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
19400 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
19410 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19420 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19440 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
19450 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
19460 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
19470 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19490 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
194a0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
194b0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
194c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
194d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
194e0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
194f0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
19500 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19510 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
19530 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
19540 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
19550 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
19560 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
19570 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
19580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19590 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
195a0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
195b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
195c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
195d0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
195e0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
195f0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
19600 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19610 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
19620 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
19630 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
19640 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19650 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19660 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
19670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
19680 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19690 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
196a0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
196b0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
196c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
196d0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
196e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
196f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19700 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
19710 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
19720 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
19730 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
19740 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19750 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
19760 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
19770 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
19780 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19790 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
197a0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
197b0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
197c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
197d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
197e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
197f0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
19800 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
19810 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19820 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19830 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19840 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
19850 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
19860 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19870 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
19880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19890 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
198a0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
198b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
198c0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
198d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
198e0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
198f0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
19900 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
19910 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
19920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19930 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
19940 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
19950 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
19960 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
19970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19980 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
19990 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
199a0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
199b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
199c0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
199d0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
199e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
199f0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
19a00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
19a10 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
19a20 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
19a30 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
19a40 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
19a50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
19a60 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
19a70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
19a80 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
19a90 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
19aa0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
19ab0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
19ac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
19ad0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
19ae0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
19af0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19b00 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19b10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
19b20 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
19b30 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
19b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
19b50 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
19b60 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
19b70 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
19b80 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
19b90 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
19ba0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
19bb0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
19bc0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
19bd0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
19be0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
19bf0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
19c00 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
19c10 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
19c20 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
19c30 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
19c40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19c50 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
19c60 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
19c70 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19c80 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
19c90 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
19ca0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
19cb0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
19cc0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
19cd0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19ce0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
19cf0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
19d00 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
19d10 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
19d20 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
19d30 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
19d40 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
19d50 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
19d60 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
19d70 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
19d80 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
19d90 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
19da0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
19db0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
19dc0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
19dd0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
19de0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
19df0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
19e00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
19e10 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
19e20 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
19e30 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
19e40 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
19e50 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
19e60 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
19e70 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
19e80 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
19e90 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
19ea0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
19eb0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
19ec0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
19ed0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
19ee0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
19ef0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
19f00 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
19f10 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
19f20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
19f30 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
19f40 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
19f50 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
19f60 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
19f70 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
19f80 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19f90 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
19fa0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
19fb0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
19fc0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
19fd0 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
19fe0 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
19ff0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a000 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
1a010 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1a020 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
1a030 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1a040 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
1a050 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1a060 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
1a070 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a080 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
1a090 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1a0a0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1a0b0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1a0c0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1a0d0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49   query..**.** ^I
1a0e0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1a0f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1a100 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1a110 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1a120 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1a130 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1a140 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1a150 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1a160 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1a170 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1a180 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1a190 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1a1a0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1a1b0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1a1c0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1a1d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a1e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a1f0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1a200 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1a210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a220 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1a230 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1a240 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1a250 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a260 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1a270 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1a280 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1a290 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1a2a0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1a2b0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1a2c0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1a2d0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1a2e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a2f0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1a300 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1a310 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1a320 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1a330 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1a340 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
1a350 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
1a360 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1a370 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1a380 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1a390 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1a3a0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1a3b0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1a3c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a3d0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1a3e0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1a3f0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1a400 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1a410 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1a420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1a430 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1a440 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1a450 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1a460 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1a470 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1a480 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1a490 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1a4a0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1a4b0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1a4c0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1a4d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1a4e0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1a4f0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1a500 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1a510 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1a520 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1a530 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a540 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1a550 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1a560 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1a570 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1a580 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1a590 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1a5a0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1a5b0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1a5c0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1a5d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1a5e0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1a5f0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1a600 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1a610 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1a620 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1a630 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1a640 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1a650 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1a660 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1a670 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1a680 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1a690 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1a6a0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1a6b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1a6c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1a6d0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1a6e0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1a6f0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1a700 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1a710 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1a720 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1a730 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1a740 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1a750 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1a760 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1a770 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1a780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a790 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1a7a0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1a7b0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1a7c0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1a7d0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1a7e0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1a7f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1a800 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1a810 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1a820 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1a830 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1a840 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1a850 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1a860 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1a870 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1a880 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1a890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1a8a0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1a8b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1a8c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1a8d0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1a8e0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1a8f0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1a900 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1a910 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1a920 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a930 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1a940 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1a950 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1a960 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
1a970 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1a980 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1a990 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1a9a0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1a9b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1a9c0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1a9d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a9e0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1a9f0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1aa00 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1aa10 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1aa20 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1aa30 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1aa40 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1aa50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1aa60 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1aa70 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1aa80 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1aa90 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1aaa0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1aab0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1aac0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1aad0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1aae0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1aaf0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1ab00 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1ab10 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1ab20 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1ab30 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1ab40 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1ab50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1ab60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1ab70 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1ab80 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1ab90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1aba0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1abb0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1abc0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1abd0 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a  s creates it if.
1abe0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1abf0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1ac00 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1ac10 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1ac20 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1ac30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1ac40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1ac50 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1ac60 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1ac70 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1ac80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ac90 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1aca0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1acb0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1acc0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1acd0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1ace0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1acf0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1ad00 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1ad10 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1ad20 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
1ad30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1ad40 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
1ad50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1ad60 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1ad70 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s,.** then the b
1ad80 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1ad90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1ada0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1adb0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1adc0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1add0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ade0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1adf0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1ae00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ae10 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1ae20 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1ae30 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1ae40 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1ae50 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ae60 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1ae70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ae80 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1ae90 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1aea0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aeb0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1aec0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1aed0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1aee0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1aef0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1af00 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1af10 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1af20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1af30 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1af40 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1af50 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1af60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1af70 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1af80 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1af90 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1afa0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1afb0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1afc0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1afd0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1afe0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1aff0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1b000 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1b010 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1b020 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1b030 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1b040 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1b050 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1b060 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1b070 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1b080 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1b090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1b0a0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1b0b0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1b0c0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1b0d0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b0e0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1b0f0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1b100 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1b110 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1b120 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1b130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b140 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1b150 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1b160 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1b170 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1b180 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1b190 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1b1a0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1b1b0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1b1c0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1b1d0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1b1e0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1b1f0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1b200 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1b210 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1b220 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1b230 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1b240 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1b250 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1b260 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1b270 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1b280 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1b290 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1b2a0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1b2b0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1b2c0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1b2d0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1b2e0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1b2f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1b300 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1b310 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1b320 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1b330 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1b340 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  losed..**.** ^Th
1b350 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b360 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1b370 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1b380 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1b390 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1b3a0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1b3b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1b3c0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1b3d0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1b3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b3f0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1b400 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1b410 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1b420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1b430 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1b440 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b450 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1b460 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1b470 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1b480 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1b490 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1b4a0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1b4b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1b4c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1b4d0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1b4e0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1b4f0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1b500 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1b510 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1b520 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1b530 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1b540 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1b550 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1b560 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1b570 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1b580 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1b590 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1b5a0 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  _v2()..*/.int sq
1b5b0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1b5c0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1b5d0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1b5e0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1b5f0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1b600 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1b610 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1b620 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1b630 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1b640 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1b650 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1b660 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1b670 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1b680 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1b690 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1b6a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1b6b0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1b6c0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1b6d0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1b6e0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1b6f0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1b700 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1b710 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1b720 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1b730 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1b740 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1b750 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1b760 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1b770 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1b780 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1b790 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1b7a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b7b0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1b7c0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1b7d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1b7e0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1b7f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1b800 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1b810 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1b820 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1b830 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1b840 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1b850 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1b860 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1b870 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1b880 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1b890 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1b8a0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1b8b0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1b8c0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1b8d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1b8e0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1b8f0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1b900 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1b910 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1b920 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1b930 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1b940 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1b950 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1b960 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1b970 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1b980 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1b990 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1b9a0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1b9b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b9c0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1b9d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b9e0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1b9f0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1ba00 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1ba10 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1ba20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1ba30 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1ba40 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1ba50 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1ba60 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1ba70 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1ba80 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1ba90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1baa0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1bab0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1bac0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1bad0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1bae0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1baf0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1bb00 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1bb10 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1bb20 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1bb30 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1bb40 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1bb50 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1bb60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1bb70 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1bb80 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1bb90 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1bba0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1bbb0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1bbc0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1bbd0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1bbe0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1bbf0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1bc00 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1bc10 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1bc20 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1bc30 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1bc40 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1bc50 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1bc60 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1bc70 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1bc80 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1bc90 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1bca0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1bcb0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1bcc0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1bcd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bce0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1bcf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1bd00 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1bd10 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1bd20 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1bd30 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1bd40 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1bd50 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1bd60 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1bd70 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1bd80 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1bd90 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1bda0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1bdb0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1bdc0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1bdd0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1bde0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1bdf0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1be00 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1be10 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1be20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1be30 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1be40 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1be50 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1be60 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1be70 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
1be80 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1be90 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1bea0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1beb0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1bec0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1bed0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1bee0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1bef0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1bf00 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1bf10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bf20 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1bf30 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1bf40 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1bf50 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1bf60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1bf70 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1bf80 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1bf90 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1bfa0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1bfb0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1bfc0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1bfd0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1bfe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1bff0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1c000 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1c010 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1c020 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1c030 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1c040 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1c050 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1c060 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1c070 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1c080 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1c090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1c0a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c0b0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1c0c0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1c0d0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1c0e0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1c0f0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1c100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1c110 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1c120 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1c130 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1c140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1c150 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1c160 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1c170 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1c180 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1c190 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1c1a0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1c1b0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1c1c0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1c1d0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1c1e0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1c1f0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1c200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1c210 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1c220 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1c230 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1c240 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1c250 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1c260 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1c270 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1c280 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1c290 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1c2a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1c2b0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
1c2c0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
1c2d0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1c2e0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1c2f0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1c300 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1c310 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1c320 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1c330 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1c340 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1c350 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c360 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1c370 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1c380 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1c390 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1c3a0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1c3b0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1c3c0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1c3d0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1c3e0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1c3f0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1c400 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1c410 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1c420 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1c430 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
1c440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1c450 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1c460 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1c470 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1c480 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
1c490 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
1c4a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
1c4b0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
1c4c0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1c4d0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1c4e0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
1c4f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
1c500 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1c510 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
1c520 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1c530 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
1c540 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1c550 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1c560 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1c570 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1c580 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1c590 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1c5a0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1c5b0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1c5c0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1c5d0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1c5e0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1c5f0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
1c600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1c610 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
1c620 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
1c630 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
1c640 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1c650 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
1c660 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
1c670 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
1c680 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
1c690 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
1c6a0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
1c6b0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
1c6c0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
1c6d0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
1c6e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
1c6f0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
1c700 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1c710 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1c720 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1c730 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1c740 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1c750 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1c760 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1c770 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1c780 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1c790 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1c7a0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1c7b0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1c7c0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1c7d0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1c7e0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1c7f0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1c800 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1c810 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1c820 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1c830 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1c840 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1c850 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1c860 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1c870 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1c880 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1c890 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1c8a0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1c8b0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1c8c0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1c8d0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1c8e0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1c8f0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1c900 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1c910 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1c920 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1c930 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1c940 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1c950 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1c960 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1c970 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1c980 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1c990 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1c9a0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1c9b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1c9c0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1c9d0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1c9e0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1c9f0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1ca00 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1ca10 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1ca20 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1ca30 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1ca40 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1ca50 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1ca60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1ca70 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1ca80 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1ca90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1caa0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1cab0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1cac0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1cad0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1cae0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1caf0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1cb00 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1cb10 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1cb20 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1cb30 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1cb40 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1cb50 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1cb60 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1cb70 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1cb80 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1cb90 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1cba0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1cbb0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1cbc0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1cbd0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1cbe0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1cbf0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1cc00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1cc10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1cc20 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1cc30 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1cc40 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1cc50 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
1cc60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1cc70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1cc80 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1cc90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cca0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1ccb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1ccc0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1ccd0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1cce0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1ccf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1cd00 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1cd10 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1cd20 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1cd30 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1cd40 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1cd50 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1cd60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1cd70 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1cd80 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1cd90 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1cda0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1cdb0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1cdc0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1cdd0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1cde0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1cdf0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1ce00 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1ce10 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1ce20 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1ce30 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1ce40 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1ce50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1ce60 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1ce70 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1ce80 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1ce90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1cea0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1ceb0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1cec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1ced0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1cee0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1cef0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1cf00 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1cf10 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1cf20 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
1cf30 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
1cf40 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
1cf50 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
1cf60 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
1cf70 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
1cf80 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
1cf90 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
1cfa0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1cfb0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1cfc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1cfd0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1cfe0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1cff0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1d000 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1d010 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1d020 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1d030 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d040 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1d050 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1d060 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1d070 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d080 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1d090 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1d0a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d0b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1d0c0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1d0d0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1d0e0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1d0f0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1d100 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d110 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1d120 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1d130 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
1d140 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
1d150 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
1d160 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1d170 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  nt.)^.**.** ^(<d
1d180 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
1d190 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
1d1a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d1b0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
1d1c0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
1d1d0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
1d1e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1d1f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
1d200 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1d210 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
1d220 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
1d230 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
1d240 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
1d250 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d260 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
1d270 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
1d280 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d290 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
1d2a0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
1d2b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d2c0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d2d0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
1d2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d2f0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
1d300 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
1d310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d320 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1d330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
1d340 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d350 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
1d360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
1d370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d380 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1d390 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
1d3a0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
1d3b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1d3c0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
1d3d0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
1d3e0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1d3f0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1d400 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
1d410 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1d420 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
1d430 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1d440 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1d450 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
1d460 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1d470 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1d480 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1d490 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1d4a0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1d4b0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1d4c0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
1d4d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1d4e0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
1d4f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d500 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
1d510 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
1d520 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1d530 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1d540 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1d550 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
1d560 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
1d570 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
1d580 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
1d590 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
1d5a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1d5b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
1d5c0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
1d5d0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1d5e0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
1d5f0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
1d600 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
1d610 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1d620 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
1d630 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
1d640 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
1d650 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
1d660 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
1d670 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1d680 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
1d690 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
1d6a0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1d6b0 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
1d6c0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
1d6d0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1d6e0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
1d6f0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
1d700 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1d710 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1d720 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1d730 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1d740 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1d750 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
1d760 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1d770 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1d780 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1d790 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1d7a0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1d7b0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1d7c0 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1d7d0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1d7e0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1d7f0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1d800 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1d810 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1d820 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1d830 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1d840 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1d850 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1d860 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1d870 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1d880 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1d890 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1d8a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1d8b0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1d8c0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1d8d0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1d8e0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
1d900 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
1d910 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
1d920 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1d930 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
1d940 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
1d950 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1d960 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1d970 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1d980 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
1d990 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
1d9a0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1d9b0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1d9c0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
1d9d0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
1d9e0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1d9f0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
1da00 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
1da10 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
1da20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1da30 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
1da40 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
1da50 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
1da60 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
1da70 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
1da80 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
1da90 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
1daa0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1dab0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1dac0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1dad0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1dae0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1daf0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1db00 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1db10 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1db20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1db30 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1db40 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1db50 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1db60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1db70 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1db80 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1db90 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1dba0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1dbb0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
1dbc0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1dbd0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
1dbe0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1dbf0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
1dc00 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1dc10 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1dc20 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1dc30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1dc40 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1dc50 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1dc60 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1dc70 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1dc80 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1dc90 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1dca0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1dcb0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1dcc0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1dcd0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1dce0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1dcf0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
1dd00 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1dd10 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1dd20 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1dd30 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1dd40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1dd50 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1dd60 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1dd70 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1dd80 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1dd90 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1dda0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1ddb0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1ddc0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1ddd0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
1dde0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1ddf0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
1de00 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
1de10 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
1de20 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
1de30 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
1de40 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
1de50 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
1de60 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
1de70 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1de80 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
1de90 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
1dea0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20   run it again.  
1deb0 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68  ^If the schema h
1dec0 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a  as changed in.**
1ded0 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65   a way that make
1dee0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1def0 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
1df00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1df10 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
1df20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
1df30 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c  CHEMA].  But unl
1df40 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ike the legacy b
1df50 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45  ehavior, [SQLITE
1df60 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e  _SCHEMA] is.** n
1df70 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  ow a fatal error
1df80 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  .  Calling [sqli
1df90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dfa0 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
1dfb0 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
1dfc0 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74  or go away.  Not
1dfd0 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  e: use [sqlite3_
1dfe0 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e  errmsg()] to fin
1dff0 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66  d the text.** of
1e000 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72   the parsing err
1e010 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  or that results 
1e020 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43  in an [SQLITE_SC
1e030 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a  HEMA] return..**
1e040 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
1e050 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
1e060 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
1e070 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1e080 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
1e090 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
1e0a0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
1e0b0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
1e0c0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
1e0d0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
1e0e0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
1e0f0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
1e100 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
1e110 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
1e120 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
1e130 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
1e140 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
1e150 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
1e160 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
1e170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
1e180 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
1e190 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
1e1a0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
1e1b0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
1e1c0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
1e1d0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
1e1e0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
1e1f0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
1e200 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
1e210 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
1e220 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1e230 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
1e240 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20  of a [parameter 
1e250 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
1e260 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63  ] in the WHERE c
1e270 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63  lause might.** c
1e280 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20  hange the query 
1e290 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
1e2a0 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73  ment, then the s
1e2b0 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a  tatement may be.
1e2c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1e2d0 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20   recompiled (as 
1e2e0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
1e2f0 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  n a schema chang
1e300 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e) on the first 
1e310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1e320 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
1e330 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74  ing any change t
1e340 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  o the .** [sqlit
1e350 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
1e360 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20  indings] of the 
1e370 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
1e380 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1e390 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1e3a0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1e3b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e3c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e3d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e3e0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e3f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e400 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1e410 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e420 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e430 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e440 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e450 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e460 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e470 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e480 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e490 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1e4a0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e4b0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e4c0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e4d0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e4e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1e4f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e500 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e510 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e520 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e530 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e540 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1e550 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e560 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e570 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e580 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e590 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e5a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e5b0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e5c0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e5d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e5e0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e5f0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e600 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e610 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1e620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e630 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1e640 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1e650 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1e660 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1e670 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1e680 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1e690 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1e6a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1e6b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1e6c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1e6d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1e6e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1e6f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1e700 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1e710 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e720 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1e730 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1e740 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1e750 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1e760 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1e770 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1e780 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1e790 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1e7a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1e7b0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1e7c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1e7d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1e7e0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1e7f0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1e800 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1e810 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1e820 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1e830 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1e840 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1e850 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1e860 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1e870 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1e880 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1e890 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1e8a0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1e8b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1e8c0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1e8d0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
1e8e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1e8f0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1e900 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1e910 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1e920 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1e930 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1e940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e950 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1e960 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1e970 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1e980 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e990 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1e9a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e9b0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
1e9c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1e9d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1e9e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1e9f0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
1ea00 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1ea10 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1ea20 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1ea30 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1ea40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ea50 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1ea60 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1ea70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ea80 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1ea90 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1eaa0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1eab0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1eac0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1ead0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1eae0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1eaf0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
1eb00 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
1eb10 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1eb20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
1eb30 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1eb40 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1eb50 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1eb60 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1eb70 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1eb80 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1eb90 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1eba0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1ebb0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1ebc0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1ebd0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1ebe0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1ebf0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1ec00 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1ec10 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1ec20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1ec30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1ec40 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1ec50 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1ec60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1ec70 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1ec80 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
1ec90 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
1eca0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1ecb0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
1ecc0 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
1ecd0 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
1ece0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
1ecf0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
1ed00 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
1ed10 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61  held.  A interna
1ed20 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
1ed30 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
1ed40 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1ed50 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
1ed60 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1ed70 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
1ed80 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1ed90 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
1eda0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1edb0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
1edc0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
1edd0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1ede0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
1edf0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ee00 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
1ee10 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
1ee20 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
1ee30 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
1ee40 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
1ee50 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1ee60 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
1ee70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
1ee80 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
1ee90 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
1eea0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
1eeb0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1eec0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1eed0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1eee0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
1eef0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
1ef00 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
1ef10 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
1ef20 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
1ef30 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
1ef40 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1ef50 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
1ef60 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
1ef70 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1ef80 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1ef90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1efa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1efb0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
1efc0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
1efd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1efe0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1eff0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
1f000 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
1f010 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
1f020 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
1f030 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1f040 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1f050 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1f060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f070 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1f080 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1f090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1f0a0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1f0b0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1f0c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1f0d0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1f0e0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1f0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1f100 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1f110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1f120 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1f130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1f140 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1f150 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1f160 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1f170 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1f180 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f190 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1f1a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1f1b0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1f1c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f1d0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1f1e0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
1f1f0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1f200 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1f210 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1f220 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1f230 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1f240 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
1f250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
1f260 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1f270 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
1f280 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
1f290 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
1f2a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1f2b0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
1f2c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1f2d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f2e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1f2f0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
1f300 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
1f310 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
1f320 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
1f330 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
1f340 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
1f350 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
1f360 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
1f370 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
1f380 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f390 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
1f3a0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
1f3b0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
1f3c0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
1f3d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
1f3e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1f3f0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
1f400 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
1f410 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
1f420 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
1f430 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
1f440 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
1f450 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
1f460 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
1f470 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
1f480 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1f490 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1f4a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
1f4b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
1f4c0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
1f4d0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
1f4e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1f4f0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
1f500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f510 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
1f520 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
1f530 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
1f540 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
1f550 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
1f560 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
1f570 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
1f580 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1f590 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
1f5a0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
1f5b0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
1f5c0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
1f5d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
1f5e0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
1f5f0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
1f600 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
1f610 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
1f620 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
1f630 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
1f640 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
1f650 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1f660 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1f670 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1f680 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f690 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1f6a0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1f6b0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1f6c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f6d0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1f6e0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1f6f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1f700 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1f710 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1f720 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1f730 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1f740 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1f750 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1f760 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1f770 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f780 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1f790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
1f7a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1f7b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1f7c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1f7d0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
1f7e0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1f7f0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1f800 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
1f810 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1f820 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1f830 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1f840 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1f850 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1f860 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1f870 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1f880 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1f890 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1f8a0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
1f8b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1f8c0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1f8d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1f8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f8f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1f900 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1f910 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
1f920 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1f930 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1f940 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
1f950 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1f960 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1f970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
1f980 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
1f990 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
1f9a0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1f9b0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
1f9c0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
1f9d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1f9e0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1f9f0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1fa00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1fa10 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
1fa20 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1fa30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1fa40 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1fa50 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1fa60 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1fa70 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1fa80 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1fa90 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1faa0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1fab0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1fac0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1fad0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
1fae0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1faf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1fb00 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1fb10 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1fb20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1fb30 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1fb40 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1fb50 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1fb60 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
1fb70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1fb80 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1fb90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1fba0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1fbb0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1fbc0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1fbd0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1fbe0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1fbf0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1fc00 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1fc10 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20 74  d with it. ^If t
1fc20 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1fc30 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1fc40 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1fc50 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1fc60 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
1fc70 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
1fc80 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
1fc90 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
1fca0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
1fcb0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
1fcc0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
1fcd0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1fce0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1fcf0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1fd00 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1fd10 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1fd20 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1fd30 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1fd40 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1fd50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1fd60 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1fd70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1fd80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1fd90 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1fda0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1fdb0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1fdc0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1fdd0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
1fde0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1fdf0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1fe00 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1fe10 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
1fe20 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
1fe30 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
1fe40 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
1fe50 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
1fe60 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
1fe70 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
1fe80 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
1fe90 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
1fea0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
1feb0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1fec0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
1fed0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
1fee0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
1fef0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1ff00 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1ff10 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1ff20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
1ff30 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
1ff40 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1ff50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1ff60 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ff70 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
1ff80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ff90 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
1ffa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ffb0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
1ffc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1ffd0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
1ffe0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
1fff0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
20000 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
20010 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
20020 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
20030 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
20040 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
20050 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
20060 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
20070 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
20080 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
20090 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
200a0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
200b0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
200c0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
200d0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
200e0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
200f0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
20100 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
20110 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
20120 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
20130 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
20140 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
20150 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
20160 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
20170 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
20180 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
20190 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
201a0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
201b0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
201c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
201d0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
201e0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
201f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
20200 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
20210 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
20220 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
20230 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20240 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
20250 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20260 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
20270 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
20280 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
20290 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
202a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
202b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
202c0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
202d0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
202e0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
202f0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
20300 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20310 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
20320 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20330 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
20340 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
20350 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
20360 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
20370 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
20380 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
20390 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
203a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
203b0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
203c0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
203d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
203e0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
203f0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20400 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20410 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
20420 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
20430 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
20440 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
20450 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
20460 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
20470 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
20480 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
20490 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
204a0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
204b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
204c0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
204d0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
204e0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
204f0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
20500 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
20510 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
20520 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
20530 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
20540 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20550 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
20560 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
20570 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
20580 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
20590 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
205a0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
205b0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
205c0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
205d0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
205e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
205f0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
20600 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
20610 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
20620 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
20630 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
20640 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
20650 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
20660 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
20670 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
20680 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
20690 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
206a0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
206b0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
206c0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
206d0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
206e0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
206f0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
20700 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
20710 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
20720 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
20730 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20740 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
20750 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20760 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
20770 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
20780 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20790 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
207a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
207b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
207c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
207d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
207e0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
207f0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
20800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
20810 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20820 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
20830 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
20840 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
20850 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
20860 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
20880 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
20890 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
208a0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
208b0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
208c0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
208d0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
208e0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
208f0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
20900 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
20910 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
20920 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
20930 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
20940 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
20950 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
20960 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
20970 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
20980 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
20990 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
209a0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
209b0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
209c0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
209d0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
209e0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
209f0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
20a00 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
20a10 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
20a20 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
20a30 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
20a40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
20a50 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
20a60 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
20a70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
20a80 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
20a90 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
20aa0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
20ab0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
20ac0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
20ad0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
20ae0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
20af0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
20b00 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
20b10 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
20b20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20b30 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
20b40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20b50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
20b60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
20b70 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
20b80 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
20b90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20ba0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
20bb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20bc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20bd0 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
20be0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
20bf0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
20c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20c10 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
20c20 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
20c30 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
20c40 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
20c50 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
20c60 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
20c70 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
20c80 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
20c90 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
20ca0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
20cb0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
20cc0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
20cd0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
20ce0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
20cf0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
20d00 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
20d10 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
20d20 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
20d30 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
20d40 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
20d50 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
20d60 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
20d70 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20d80 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
20d90 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
20da0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
20db0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20dc0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
20dd0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
20de0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
20df0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
20e00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20e10 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
20e20 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
20e30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20e40 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
20e50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
20e60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
20e70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
20e80 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
20e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20ea0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
20eb0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
20ec0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
20ed0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
20ee0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
20ef0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
20f00 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
20f10 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
20f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20f30 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
20f40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20f50 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
20f60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
20f70 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
20f80 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
20f90 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
20fa0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
20fb0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
20fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20fd0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
20fe0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
20ff0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
21000 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
21010 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
21020 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
21030 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
21040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21050 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
21060 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
21070 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
21080 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
21090 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
210a0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
210b0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
210c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
210d0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
210e0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
210f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
21100 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21110 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21120 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
21130 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
21140 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
21150 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
21160 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
21170 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
21180 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
21190 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
211a0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
211b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
211c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
211d0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
211e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
211f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
21200 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
21210 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
21220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
21230 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
21240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
21250 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
21260 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
21270 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
21280 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
21290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
212a0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
212b0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
212c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
212d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
212e0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
212f0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
21300 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
21310 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
21320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
21330 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
21340 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
21350 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
21360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21370 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
21380 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
21390 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
213a0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
213b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
213c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
213d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
213e0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
213f0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
21400 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
21410 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
21420 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
21430 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
21440 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
21450 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
21460 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
21470 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
21480 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
21490 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
214a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
214b0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
214c0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
214d0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
214e0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
214f0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
21500 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
21510 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
21520 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
21530 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
21540 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
21550 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
21560 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
21570 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
21580 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
21590 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
215a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
215b0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
215c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
215d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
215e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
215f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21600 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
21610 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
21620 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
21630 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
21640 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
21650 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
21660 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
21670 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
21680 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
21690 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
216a0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
216b0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
216c0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
216d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
216e0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
216f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
21700 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
21710 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
21720 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
21730 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
21740 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
21750 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
21760 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
21770 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
21780 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
21790 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
217a0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
217b0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
217c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
217d0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
217e0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
217f0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
21800 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
21810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21820 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
21830 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
21840 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
21850 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
21860 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
21870 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
21880 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
21890 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
218a0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
218b0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
218c0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
218d0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
218e0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
218f0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
21900 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
21910 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
21920 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
21930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21940 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
21950 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
21960 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
21970 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
21980 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
21990 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
219a0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
219b0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
219c0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
219d0 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
219e0 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
219f0 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
21a00 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
21a10 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
21a20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
21a30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
21a40 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
21a50 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
21a60 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
21a70 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
21a80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
21a90 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
21aa0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
21ab0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
21ac0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
21ad0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
21ae0 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
21af0 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
21b00 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
21b10 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
21b20 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
21b30 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
21b40 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
21b50 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
21b60 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
21b70 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
21b80 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
21b90 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
21ba0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
21bb0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
21bc0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
21bd0 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
21be0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
21bf0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
21c00 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
21c10 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
21c20 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
21c30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
21c40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
21c50 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
21c60 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
21c70 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
21c80 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
21c90 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
21ca0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
21cb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
21cc0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
21cd0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
21ce0 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
21cf0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
21d00 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
21d10 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
21d20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
21d30 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
21d40 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
21d50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
21d60 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
21d70 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
21d80 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
21d90 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
21da0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21db0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
21dc0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
21dd0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
21de0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
21df0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
21e00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21e10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
21e20 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
21e30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
21e40 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
21e50 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
21e60 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
21e70 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21e80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
21e90 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
21ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21eb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
21ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21ed0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
21ee0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
21ef0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
21f00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
21f10 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
21f20 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
21f30 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
21f40 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
21f50 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
21f60 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
21f70 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
21f80 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
21f90 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
21fa0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
21fb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
21fc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21fd0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
21fe0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
21ff0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
22000 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
22010 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
22020 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
22030 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
22040 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
22050 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
22060 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
22070 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
22080 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
22090 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
220a0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
220b0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
220c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
220d0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
220e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
220f0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
22100 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
22110 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22120 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
22130 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
22140 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
22150 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
22160 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
22170 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
22180 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
22190 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
221a0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
221b0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
221c0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
221d0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
221e0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
221f0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
22200 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
22210 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
22220 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
22230 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
22240 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
22250 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
22260 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
22270 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
22280 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
22290 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
222a0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
222b0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
222c0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
222d0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
222e0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
222f0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
22300 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
22310 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
22320 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
22330 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
22340 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
22350 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
22360 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
22370 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
22380 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
22390 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
223a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
223b0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
223c0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
223d0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
223e0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
223f0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
22400 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
22410 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
22420 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22430 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
22450 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
22460 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
22470 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
22480 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
22490 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
224a0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
224b0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
224c0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
224d0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
224e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
224f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
22500 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
22510 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
22520 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
22530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22540 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
22550 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
22560 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
22570 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
22580 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
22590 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
225a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
225b0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
225c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
225d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
225e0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
225f0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
22600 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
22610 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
22620 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
22630 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
22640 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22650 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22660 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22670 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
22680 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
22690 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
226a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
226b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
226c0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
226d0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
226e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
226f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
22700 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
22710 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
22720 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
22730 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
22740 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
22750 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
22760 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
22770 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
22780 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
22790 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
227a0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
227b0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
227c0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
227d0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
227e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
227f0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
22800 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
22810 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
22820 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
22830 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
22840 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
22850 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
22860 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
22870 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
22880 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
22890 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
228a0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
228b0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
228c0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
228d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
228e0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
228f0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
22900 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
22910 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
22920 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
22930 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
22940 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
22950 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
22960 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
22970 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
22980 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
22990 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
229a0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
229b0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
229c0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
229d0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
229e0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
229f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
22a00 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
22a10 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
22a20 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
22a30 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
22a40 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
22a50 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
22a60 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
22a70 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
22a80 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22a90 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
22aa0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
22ab0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
22ac0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
22ad0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
22ae0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
22af0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
22b00 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
22b10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
22b20 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
22b30 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
22b40 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
22b50 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
22b60 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
22b70 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
22b80 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
22b90 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
22ba0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
22bb0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
22bc0 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
22bd0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
22be0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
22bf0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
22c00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
22c10 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
22c20 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
22c30 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
22c40 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
22c50 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
22c60 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
22c70 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
22c80 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
22c90 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
22ca0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
22cb0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
22cc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
22cd0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
22ce0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
22cf0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
22d00 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
22d10 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
22d20 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
22d30 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
22d40 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
22d50 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
22d60 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
22d70 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
22d80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22d90 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
22da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22db0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
22dc0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
22dd0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
22de0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
22df0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
22e00 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
22e10 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
22e20 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
22e30 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
22e40 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
22e50 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
22e60 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
22e70 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
22e80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22e90 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
22ea0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
22eb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
22ec0 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
22ed0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
22ee0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
22ef0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
22f00 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
22f10 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
22f20 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
22f30 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
22f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22f50 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
22f60 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
22f70 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
22f80 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
22f90 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
22fa0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
22fb0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
22fc0 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
22fd0 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65  .23.1, it was re
22fe0 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20  quired.** after 
22ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
23000 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
23010 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
23020 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a  ITE_ROW] that.**
23030 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23040 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  )] be called bef
23050 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
23060 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
23070 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
23080 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
23090 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
230a0 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73  reset()] in this
230b0 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65   way would.** re
230c0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
230d0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
230e0 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  n from sqlite3_s
230f0 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
23100 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36  r.** version 3.6
23110 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
23120 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c  tep() began call
23130 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
23140 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61  et()] .** automa
23150 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
23160 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
23170 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69  her than returni
23180 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
23190 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  E].  .**.** <b>G
231a0 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
231b0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
231c0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
231d0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
231e0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
231f0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
23200 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
23210 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
23220 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
23230 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
23240 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
23250 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
23260 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
23270 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
23280 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
23290 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
232a0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
232b0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
232c0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
232d0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
232e0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
232f0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
23300 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
23310 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
23320 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
23330 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
23340 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
23350 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
23360 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
23370 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
23380 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
23390 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
233a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
233b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
233c0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
233d0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
233e0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
233f0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
23400 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
23410 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
23420 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
23430 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
23440 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
23450 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
23460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
23470 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
23480 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
23490 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
234a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
234b0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
234c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
234d0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
234e0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
234f0 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
23500 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
23510 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
23520 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
23530 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
23540 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
23550 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
23560 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
23570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
23580 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
23590 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
235a0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
235b0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
235c0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
235d0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
235e0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
235f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
23600 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
23610 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
23620 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
23630 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
23640 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
23650 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
23660 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
23670 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
23680 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  ointer..**.** Se
23690 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
236a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
236b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
236c0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
236d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
236e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
236f0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
23700 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
23710 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
23720 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
23730 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
23740 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
23750 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
23760 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
23770 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
23780 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
23790 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
237a0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
237b0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
237c0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
237d0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
237e0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
237f0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23800 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
23810 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
23820 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
23830 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
23840 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
23850 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
23860 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
23870 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
23880 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
23890 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
238a0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
238b0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
238c0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
238d0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
238e0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
238f0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
23900 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
23910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23920 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
23930 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
23940 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
23950 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
23960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23970 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
23980 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
23990 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
239a0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
239b0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
239c0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
239d0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
239e0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
239f0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
23a00 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
23a10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
23a20 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
23a30 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
23a40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
23a50 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
23a60 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
23a70 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
23a80 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
23a90 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
23aa0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
23ab0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
23ac0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
23ad0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
23ae0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
23af0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23b00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
23b10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23b20 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
23b30 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
23b40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
23b50 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
23b60 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
23b70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23b80 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
23b90 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
23ba0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
23bb0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
23bc0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
23bd0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
23be0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
23bf0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
23c00 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
23c10 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
23c20 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
23c30 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
23c40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23c50 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
23c60 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
23c70 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
23c80 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
23c90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
23ca0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
23cb0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
23cc0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
23cd0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
23ce0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
23cf0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
23d00 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
23d10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
23d20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
23d30 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
23d40 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
23d50 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
23d60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23d70 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
23d80 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
23d90 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
23da0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
23db0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23dc0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
23dd0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
23de0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
23df0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
23e00 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
23e10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23e20 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
23e30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
23e40 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
23e50 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
23e60 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
23e70 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
23e80 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
23e90 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
23ea0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
23eb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
23ec0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23ed0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
23ee0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
23ef0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
23f00 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
23f10 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
23f20 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
23f30 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
23f40 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
23f50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23f60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
23f70 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
23f80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
23f90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
23fa0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
23fb0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
23fc0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
23fd0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
23fe0 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
23ff0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
24000 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
24010 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
24020 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
24030 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
24040 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
24050 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
24060 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
24070 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
24080 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
24090 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
240a0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
240b0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
240c0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
240d0 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
240e0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
240f0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
24100 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
24110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
24120 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
24130 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
24140 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
24150 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
24160 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
24170 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
24180 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
24190 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
241a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
241b0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
241c0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
241d0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
241e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
241f0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
24200 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
24210 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
24220 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
24230 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
24240 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
24250 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
24260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24270 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
24280 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
24290 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
242a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
242b0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
242c0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
242d0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
242e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
242f0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
24300 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
24310 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
24320 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
24330 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
24340 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
24350 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
24360 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
24370 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
24380 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
24390 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
243a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
243b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
243c0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
243d0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
243e0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
243f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
24400 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
24410 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
24420 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
24430 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
24440 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
24450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24460 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
24470 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
24480 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
24490 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
244a0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
244b0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
244c0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
244d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
244e0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
244f0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e  ength BLOB is an
24500 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
24510 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
24520 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
24530 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
24540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24550 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
24560 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
24570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24580 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
24590 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
245a0 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
245b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
245c0 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
245d0 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72  ** ^The zero ter
245e0 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
245f0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
24600 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  count..**.** ^Th
24610 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
24620 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
24630 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
24640 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
24650 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24660 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
24670 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
24680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
24690 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
246a0 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
246b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
246c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
246d0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
246e0 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
246f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24700 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
24710 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
24720 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
24730 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
24740 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
24750 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
24760 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
24770 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24780 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
24790 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
247a0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
247b0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
247c0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
247d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
247e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
247f0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
24800 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
24810 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
24820 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
24830 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
24840 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
24850 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
24860 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
24870 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
24880 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
24890 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
248a0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
248b0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
248c0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
248d0 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
248e0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
248f0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
24900 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
24910 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
24920 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
24930 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
24940 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
24950 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
24960 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
24970 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
24980 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
24990 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
249a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
249b0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
249c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
249d0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
249e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
249f0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
24a00 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
24a10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
24a20 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
24a30 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
24a40 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
24a50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
24a60 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
24a70 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
24a80 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
24a90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
24aa0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
24ab0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
24ac0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
24ad0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
24ae0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
24af0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
24b00 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
24b10 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
24b20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
24b30 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
24b40 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
24b50 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
24b60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
24b70 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
24b80 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
24b90 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
24ba0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
24bb0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
24bc0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
24bd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
24be0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
24bf0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
24c00 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
24c10 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
24c20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
24c30 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
24c40 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
24c50 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
24c60 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
24c70 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
24c80 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
24c90 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
24ca0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
24cb0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
24cc0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
24cd0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
24ce0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
24cf0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
24d00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
24d10 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
24d20 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
24d30 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
24d40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
24d50 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
24d60 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
24d70 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
24d80 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
24d90 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
24da0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
24db0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
24dc0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
24dd0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
24de0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
24df0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
24e00 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
24e10 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
24e20 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
24e30 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
24e40 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
24e50 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
24e60 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
24e70 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
24e80 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
24e90 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
24ea0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
24eb0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
24ec0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
24ed0 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  mmers..**.** ^No
24ee0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
24ef0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
24f00 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
24f10 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
24f20 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
24f30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24f40 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
24f50 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
24f60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
24f70 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
24f80 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
24f90 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72  ** ^(Type conver
24fa0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
24fb0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
24fc0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
24fd0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
24fe0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
24ff0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
25000 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
25010 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
25020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
25030 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
25040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25050 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
25060 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
25070 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
25080 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
25090 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
250a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
250b0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
250c0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
250d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
250e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
250f0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
25100 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
25110 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
25120 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
25130 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
25140 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
25150 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
25160 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
25170 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
25180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25190 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
251a0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
251b0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
251c0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
251d0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
251e0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
251f0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
25200 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  l>)^.**.** ^Conv
25210 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
25220 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
25230 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
25240 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
25250 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
25260 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
25270 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
25280 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
25290 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
252a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
252b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
252c0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
252d0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
252e0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
252f0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
25300 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
25310 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
25320 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
25330 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
25340 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
25350 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
25360 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
25370 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
25380 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65  **.** ^(The safe
25390 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
253a0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
253b0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
253c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
253d0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
253e0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
253f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
25400 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
25410 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
25420 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
25430 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
25440 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
25450 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
25460 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
25470 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
25480 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
25490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
254a0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
254b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
254c0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
254d0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
254e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
254f0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
25500 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25510 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
25520 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
25530 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
25540 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
25550 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
25560 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
25570 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
25580 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
25590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
255a0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
255b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
255c0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
255d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
255e0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
255f0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
25600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25610 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
25620 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
25630 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
25640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25650 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
25660 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
25670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25680 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
25690 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
256a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
256b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
256c0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
256d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
256e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
256f0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
25700 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
25710 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
25720 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
25730 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
25740 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
25750 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
25760 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
25770 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
25780 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
25790 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
257a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
257b0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
257c0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
257d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
257e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
257f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
25800 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
25810 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
25820 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
25830 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
25840 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
25850 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
25860 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
25870 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
25880 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
25890 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
258a0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
258b0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
258c0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
258d0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
258e0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
258f0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
25900 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
25910 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
25920 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
25930 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
25940 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
25950 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
25960 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
25970 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
25980 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25990 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
259a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
259b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
259c0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
259d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
259e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
259f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
25a00 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
25a10 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
25a20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25a30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
25a40 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
25a50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25a60 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
25a70 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
25a80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
25a90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25aa0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
25ab0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25ac0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
25ad0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25ae0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
25af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25b00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
25b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
25b30 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
25b40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25b50 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
25b60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25b70 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
25b80 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25ba0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
25bb0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
25bc0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
25bd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25be0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
25bf0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
25c00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25c10 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
25c20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
25c30 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
25c40 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78  sfully or not ex
25c50 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
25c60 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  hen.** SQLITE_OK
25c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49   is returned. ^I
25c80 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
25c90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
25ca0 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b  led then an.** [
25cb0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
25cc0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
25cd0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
25ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
25cf0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
25d00 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
25d10 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
25d20 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
25d30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25d40 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76  ent].  ^If the v
25d50 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
25d60 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
25d70 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
25d80 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
25d90 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
25da0 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
25db0 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
25dc0 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
25dd0 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
25de0 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f  rrupt]..** ^Inco
25df0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
25e00 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
25e10 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
25e20 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
25e30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
25e40 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
25e50 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
25e60 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
25e70 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
25e80 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  _ABORT]..*/.int 
25e90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25eb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25ec0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
25ed0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
25ee0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
25ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
25f00 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
25f10 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
25f20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25f30 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
25f40 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
25f50 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
25f60 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
25f70 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
25f80 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
25f90 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
25fa0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
25fb0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
25fc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25fd0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
25fe0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
25ff0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
26000 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
26010 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
26020 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
26030 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
26040 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
26050 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
26060 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
26070 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26080 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
26090 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
260a0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
260b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
260c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
260d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
260e0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
260f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26100 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
26110 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
26120 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
26130 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
26140 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
26150 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
26160 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
26170 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
26180 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
26190 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
261a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
261b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
261c0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
261d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
261e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
261f0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
26200 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
26210 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
26220 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
26230 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
26240 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
26250 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
26260 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
26270 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
26280 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
26290 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
262a0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
262b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
262c0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
262d0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
262e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
262f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26300 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
26310 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
26320 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
26330 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
26340 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
26350 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
26360 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26370 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
26380 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
26390 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
263a0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
263b0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
263c0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
263d0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
263e0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
263f0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
26400 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
26410 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
26420 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
26430 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
26440 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
26450 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
26460 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
26470 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
26480 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
26490 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
264a0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
264b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
264c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
264d0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
264e0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
264f0 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
26500 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
26510 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26520 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
26530 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
26540 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26550 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ()..**.** ^The f
26560 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
26570 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
26580 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
26590 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
265a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
265b0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
265c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
265d0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
265e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
265f0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
26600 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26610 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
26620 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
26630 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
26640 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
26650 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ately..**.** The
26660 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
26670 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
26680 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
26690 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
266a0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
266b0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
266c0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
266d0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
266e0 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
266f0 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
26700 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
26710 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
26720 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
26730 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
26740 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61  racters.  ^Any a
26750 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
26760 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
26770 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
26780 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
26790 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
267a0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
267b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
267c0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
267d0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
267e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
267f0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
26800 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
26810 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
26820 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
26830 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
26840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
26850 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
26860 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
26870 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
26880 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
26890 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
268a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
268b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
268c0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
268d0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
268e0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
268f0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
26900 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
26910 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
26920 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
26930 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
26940 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
26950 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
26960 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
26970 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
26980 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
26990 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
269a0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
269b0 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
269c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
269d0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
269e0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
269f0 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
26a00 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
26a10 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
26a20 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
26a30 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
26a40 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
26a50 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
26a60 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41  han another.  ^A
26a70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
26a80 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  y.** invoke sqli
26a90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26aa0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
26ab0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26ac0 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
26ad0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
26ae0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
26af0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
26b00 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
26b10 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  Rep..** ^When mu
26b20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
26b30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
26b40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
26b50 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
26b60 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
26b70 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
26b80 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
26b90 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
26ba0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
26bb0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
26bc0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
26bd0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
26be0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
26bf0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
26c00 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
26c10 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
26c20 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
26c30 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
26c40 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
26c50 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
26c60 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
26c70 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
26c80 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
26c90 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
26ca0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
26cb0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
26cc0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
26cd0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].)^.**.** The s
26ce0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
26cf0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
26d00 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
26d10 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
26d20 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
26d30 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
26d40 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
26d50 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
26d60 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
26d70 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
26d80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
26d90 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
26da0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
26db0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
26dc0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
26dd0 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
26de0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
26df0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
26e00 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
26e10 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
26e20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
26e30 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
26e40 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
26e50 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
26e60 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
26e70 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
26e80 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
26e90 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
26ea0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
26eb0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
26ec0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
26ed0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
26ee0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
26ef0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
26f00 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
26f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
26f20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
26f30 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
26f40 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
26f50 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
26f60 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
26f70 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
26f80 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
26f90 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
26fa0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
26fb0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
26fc0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
26fd0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
26fe0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
26ff0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
27000 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
27010 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
27020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
27030 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
27040 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
27050 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
27060 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
27070 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
27080 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
27090 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
270a0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
270b0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
270c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
270d0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
270e0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
270f0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
27100 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
27110 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
27120 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
27130 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
27140 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
27150 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
27160 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
27170 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
27180 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
27190 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
271a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
271b0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
271c0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
271d0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
271e0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
271f0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
27200 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
27210 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
27220 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27230 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ons..** ^The fir
27240 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  st application-d
27250 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27260 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d  with a given nam
27270 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a  e overrides all.
27280 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** built-in func
27290 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d  tions in the sam
272a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
272b0 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65  ection] with the
272c0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e   same name..** ^
272d0 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69  Subsequent appli
272e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
272f0 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  unctions of the 
27300 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f  same name only o
27310 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f  verride .** prio
27320 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  r application-de
27330 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
27340 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63  that are an exac
27350 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a  t match for the.
27360 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  ** number of par
27370 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66  ameters and pref
27380 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a  erred encoding..
27390 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
273a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
273b0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
273c0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
273d0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
273e0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
273f0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
27400 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
27410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27420 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
27430 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
27440 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
27450 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
27460 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
27470 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
27480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27490 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
274a0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
274b0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
274c0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
274d0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
274e0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
274f0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
27500 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27510 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
27520 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
27530 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
27540 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
27550 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
27560 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
27570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
27580 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
27590 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
275a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
275b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
275c0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
275d0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
275e0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
275f0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
27600 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
27610 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
27620 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
27630 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
27640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27650 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
27660 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
27670 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
27680 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
27690 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
276a0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
276b0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
276c0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
276d0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
276e0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
276f0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
27700 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
27710 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
27720 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
27730 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
27740 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
27750 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
27760 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
27770 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
27780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27790 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
277a0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
277b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
277c0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
277d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
277e0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
277f0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
27800 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
27810 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
27820 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
27830 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
27840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
27850 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
27860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
27870 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
27880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
27890 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
278a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
278b0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
278c0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
278d0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
278e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
278f0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
27900 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
27910 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
27920 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
27930 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
27940 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
27950 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27960 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
27970 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
27980 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
27990 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
279a0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
279b0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
279c0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
279d0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
279e0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
279f0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
27a00 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
27a10 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
27a20 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
27a30 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
27a40 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
27a50 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
27a60 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
27a70 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
27a80 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
27a90 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
27aa0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
27ab0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
27ac0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
27ad0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
27ae0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
27af0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
27b00 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
27b10 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
27b20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27b30 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
27b40 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
27b50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
27b60 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
27b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
27b80 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
27b90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
27ba0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
27bb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
27bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
27bd0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
27be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
27bf0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
27c00 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
27c10 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
27c20 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
27c30 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
27c40 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
27c50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
27c60 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
27c70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
27c80 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
27c90 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
27ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27cb0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
27cc0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
27cd0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
27ce0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
27cf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27d00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
27d10 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
27d20 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
27d30 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
27d40 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
27d50 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
27d60 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
27d70 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
27d80 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
27d90 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
27da0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
27db0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
27dc0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
27dd0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
27de0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27df0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
27e00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27e10 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
27e20 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
27e30 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
27e40 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
27e50 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
27e60 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
27e70 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
27e80 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
27e90 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
27ea0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27eb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27ec0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
27ed0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
27ee0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
27ef0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
27f00 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27f10 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
27f20 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
27f30 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
27f40 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
27f50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
27f70 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
27f80 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
27f90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
27fa0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
27fb0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
27fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
27fd0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
27fe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
27ff0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
28000 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
28010 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
28020 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
28030 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
28040 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
28050 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
28060 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
28070 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
28080 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
28090 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
280a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
280b0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
280c0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
280d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
280e0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
280f0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
28100 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
28110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
28120 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
28130 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
28140 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
28150 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
28160 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
28170 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
28180 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
28190 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
281a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
281b0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
281c0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
281d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
281e0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
281f0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
28200 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
28210 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
28220 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
28230 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
28240 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
28250 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
28260 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
28270 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
28280 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
28290 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
282a0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
282b0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
282c0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
282d0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
282e0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
282f0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
28300 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
28310 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
28320 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
28330 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
28340 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
28350 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
28360 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
28370 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
28380 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
28390 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
283a0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
283b0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
283c0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
283d0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
283e0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
283f0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
28400 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
28410 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
28420 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
28430 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
28440 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
28450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28460 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
28470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28480 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
28490 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
284a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
284b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
284c0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
284d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
284e0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
284f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
28500 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
28510 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
28520 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
28530 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
28540 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
28550 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
28560 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
28570 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
28580 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28590 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
285a0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
285b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
285c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
285d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
285e0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
285f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28600 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28610 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
28620 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
28630 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
28640 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
28650 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28660 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
28670 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
28680 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
28690 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
286a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
286b0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
286c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
286d0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
286e0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
286f0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
28700 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
28710 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
28720 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
28730 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
28740 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
28750 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28760 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
28770 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28780 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28790 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
287a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
287b0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
287c0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
287d0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
287e0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
287f0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
28800 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
28810 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
28820 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
28830 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
28840 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
28850 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
28860 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
28870 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
28880 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
28890 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
288a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
288b0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
288c0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
288d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
288e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
288f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
28900 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
28910 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
28920 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
28930 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
28940 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
28950 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
28960 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
28970 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
28980 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28990 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
289a0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
289b0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
289c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
289d0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
289e0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
289f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
28a00 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
28a10 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
28a20 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
28a30 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
28a40 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
28a50 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
28a60 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
28a70 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
28a80 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
28a90 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
28aa0 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
28ab0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
28ac0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
28ad0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
28ae0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28af0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
28b00 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
28b10 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
28b20 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
28b30 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
28b40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
28b50 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
28b60 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
28b70 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
28b80 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
28b90 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
28ba0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28bb0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
28bc0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
28bd0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
28be0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
28bf0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
28c00 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
28c10 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
28c20 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
28c30 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
28c40 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
28c50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28c60 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
28c70 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
28c80 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
28c90 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
28ca0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
28cb0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
28cc0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
28cd0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
28ce0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
28cf0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
28d00 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
28d10 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
28d20 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
28d30 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
28d40 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
28d50 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
28d60 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
28d70 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
28d80 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
28d90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
28da0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
28db0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
28dc0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
28dd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
28de0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
28df0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
28e00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
28e10 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
28e20 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
28e30 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
28e40 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
28e50 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
28e60 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
28e70 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
28e80 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
28e90 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
28ea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
28eb0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
28ec0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
28ed0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
28ee0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
28ef0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
28f00 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
28f10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
28f20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
28f30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28f40 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
28f50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
28f60 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
28f70 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
28f80 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
28f90 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
28fa0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
28fb0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
28fc0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
28fd0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
28fe0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
28ff0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
29000 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29010 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
29020 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
29030 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
29040 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
29050 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
29060 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
29070 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
29080 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
29090 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
290a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
290b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
290c0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
290d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
290e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
290f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
29100 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
29110 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
29120 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
29130 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
29140 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
29150 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
29160 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
29170 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
29180 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29190 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
291a0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
291b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
291c0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
291d0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
291e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
291f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29200 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
29210 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29220 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
29230 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
29240 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
29250 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29260 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
29270 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
29280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
29290 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
292a0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
292b0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
292c0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
292d0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
292e0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
292f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
29300 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
29310 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
29320 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
29330 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
29340 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
29350 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
29360 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
29370 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
29380 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
29390 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
293a0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
293b0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
293c0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
293d0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
293e0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
293f0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
29400 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
29410 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
29420 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
29430 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
29440 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
29450 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
29460 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
29470 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29480 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
29490 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
294a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
294b0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
294c0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
294d0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
294e0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
294f0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
29500 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
29510 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
29520 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
29530 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
29540 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
29550 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
29560 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
29570 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
29580 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
29590 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
295a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
295b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
295c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
295d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
295e0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
295f0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
29600 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
29610 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
29620 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
29630 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
29640 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29650 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29660 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
29670 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
29680 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
29690 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
296a0 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
296b0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
296c0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
296d0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
296e0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
296f0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
29700 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
29710 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
29720 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
29730 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
29740 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29750 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
29760 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
29770 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
29780 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
29790 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
297a0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
297b0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
297c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
297d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
297e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
297f0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
29800 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
29810 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
29820 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
29830 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
29840 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
29850 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
29860 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
29870 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
29880 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
29890 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
298a0 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
298b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
298c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
298d0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
298e0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
298f0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
29900 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
29910 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
29920 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
29930 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
29940 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
29950 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
29960 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
29970 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
29980 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
29990 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
299a0 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
299b0 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
299c0 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
299d0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
299e0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
299f0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
29a00 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
29a10 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
29a20 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
29a30 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
29a40 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
29a50 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
29a60 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
29a70 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
29a80 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
29a90 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
29aa0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
29ab0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
29ac0 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
29ad0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
29ae0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
29af0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
29b00 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
29b10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
29b20 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
29b30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
29b40 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
29b50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
29b60 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
29b70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
29b80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29b90 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
29ba0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
29bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29bc0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
29bd0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
29be0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
29bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
29c00 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
29c10 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
29c20 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
29c30 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
29c40 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
29c50 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
29c60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29c70 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
29c80 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
29c90 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
29ca0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
29cb0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
29cc0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
29cd0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
29ce0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
29cf0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
29d00 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
29d10 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
29d20 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
29d30 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
29d40 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
29d50 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
29d60 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
29d70 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
29d80 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
29d90 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
29da0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
29db0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
29dc0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
29dd0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
29de0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
29df0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
29e00 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
29e10 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
29e20 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
29e30 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
29e40 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
29e50 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
29e60 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
29e70 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
29e80 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
29e90 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
29ea0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
29eb0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
29ec0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
29ed0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
29ee0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
29ef0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
29f00 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
29f10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
29f20 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
29f30 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
29f40 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
29f50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
29f60 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
29f70 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
29f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
29f90 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
29fa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
29fb0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
29fc0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
29fd0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
29fe0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
29ff0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2a000 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
2a010 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2a020 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
2a030 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
2a040 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2a050 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2a060 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2a070 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2a080 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
2a090 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
2a0a0 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2a0b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2a0c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a0d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2a0e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2a0f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2a100 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2a110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2a120 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
2a130 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
2a140 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
2a150 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
2a160 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
2a170 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
2a180 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
2a190 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
2a1a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2a1b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a1c0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
2a1d0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
2a1e0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2a1f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a200 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2a210 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
2a220 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
2a230 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
2a240 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
2a250 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
2a260 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
2a270 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2a280 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a290 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
2a2a0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2a2b0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2a2c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a2d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2a2e0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
2a2f0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
2a300 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
2a310 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2a320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a330 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2a340 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a350 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2a360 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2a370 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2a380 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2a390 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2a3a0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
2a3b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2a3c0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2a3d0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2a3e0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2a3f0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2a400 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a410 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2a420 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2a430 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
2a440 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
2a450 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2a460 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
2a470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a480 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
2a490 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
2a4a0 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
2a4b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2a4c0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
2a4d0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
2a4e0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
2a4f0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
2a500 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a520 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2a530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2a540 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
2a550 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2a560 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
2a570 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
2a580 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
2a590 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2a5a0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2a5b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2a5c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2a5d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
2a5e0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2a5f0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2a600 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
2a610 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2a620 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
2a630 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2a640 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
2a650 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2a660 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2a670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a680 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2a690 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a6a0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2a6b0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
2a6c0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2a6d0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2a6e0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2a6f0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2a700 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2a710 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2a720 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
2a730 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
2a740 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
2a750 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2a760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2a770 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2a780 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
2a790 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
2a7a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2a7b0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
2a7c0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
2a7d0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
2a7e0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
2a7f0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
2a800 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
2a810 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
2a820 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2a830 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2a840 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2a850 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
2a860 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
2a870 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
2a880 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
2a890 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
2a8a0 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
2a8b0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2a8c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2a8d0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2a8e0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
2a8f0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
2a900 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
2a910 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a920 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
2a930 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2a940 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2a950 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
2a960 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2a970 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2a980 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
2a990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a9a0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2a9b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2a9c0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2a9d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a9e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a9f0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2aa00 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2aa10 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2aa20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2aa30 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
2aa40 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2aa50 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
2aa60 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2aa70 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2aa80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2aa90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2aaa0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
2aab0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2aac0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2aad0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2aae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aaf0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
2ab00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ab10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2ab20 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2ab30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ab40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
2ab50 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2ab60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ab70 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
2ab80 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
2ab90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aba0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2abb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2abc0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2abd0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2abe0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2abf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ac00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ac10 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2ac20 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2ac30 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2ac40 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2ac50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2ac60 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2ac70 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2ac80 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2ac90 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2aca0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
2acb0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
2acc0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
2acd0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
2ace0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2acf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2ad00 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2ad10 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
2ad20 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2ad30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2ad40 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2ad50 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
2ad60 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
2ad70 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
2ad80 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
2ad90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
2ada0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2adb0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2adc0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
2add0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2ade0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2adf0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2ae00 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
2ae10 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
2ae20 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2ae30 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
2ae40 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
2ae50 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
2ae60 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
2ae70 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
2ae80 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
2ae90 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
2aea0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2aeb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2aec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2aed0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2aee0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2aef0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
2af00 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
2af10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
2af20 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
2af30 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
2af40 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
2af50 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2af60 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2af70 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2af80 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
2af90 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2afa0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2afb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2afc0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
2afd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
2afe0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2aff0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2b000 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2b010 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
2b020 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
2b030 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
2b040 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
2b050 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
2b060 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
2b070 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2b080 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
2b090 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2b0a0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
2b0b0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
2b0c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2b0d0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2b0e0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2b0f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2b100 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2b110 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2b120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b130 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2b140 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2b150 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2b160 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2b170 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2b180 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2b190 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2b1a0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2b1b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2b1c0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2b1d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b1e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2b1f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b200 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
2b210 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b220 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b230 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
2b240 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
2b250 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b260 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
2b270 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
2b280 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
2b290 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2b2a0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2b2b0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
2b2c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b2d0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
2b2e0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
2b2f0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
2b300 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2b310 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
2b320 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
2b330 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
2b340 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
2b350 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
2b360 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
2b370 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b380 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2b390 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2b3a0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2b3b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b3c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2b3d0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2b3e0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2b3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b400 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2b410 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2b420 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2b430 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2b440 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2b450 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2b460 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
2b470 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
2b480 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
2b490 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b4a0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
2b4b0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
2b4c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
2b4d0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
2b4e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2b4f0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2b500 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2b510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b520 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2b530 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b540 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2b550 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
2b560 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b570 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
2b580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b590 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2b5a0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2b5b0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2b5c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b5d0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
2b5e0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2b5f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2b600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b610 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
2b620 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2b630 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b640 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
2b650 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2b660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b670 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
2b680 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b690 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2b6a0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
2b6b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b6c0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2b6d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2b6e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b6f0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2b700 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2b710 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
2b720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2b730 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b740 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
2b750 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2b760 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
2b770 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2b780 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b790 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2b7a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2b7b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b7c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2b7d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b7e0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2b7f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2b800 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2b810 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2b820 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b830 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
2b840 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2b850 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2b860 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2b870 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b880 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
2b890 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2b8a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
2b8b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b8c0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2b8d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2b8e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b8f0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
2b900 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
2b910 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  es.**.** These f
2b920 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
2b930 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
2b940 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2b950 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   to the.** [data
2b960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b970 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2b980 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2b9a0 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
2b9b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2b9c0 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
2b9d0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2b9e0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2b9f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2ba00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2ba10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2ba20 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2ba30 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
2ba40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ba50 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e 20  lation16(). ^In 
2ba60 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
2ba70 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
2ba80 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
2ba90 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2baa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2bab0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
2bac0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
2bad0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
2bae0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
2baf0 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53  _UTF16LE], or [S
2bb00 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2bb10 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2bb20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
2bb30 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
2bb40 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
2bb50 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
2bb60 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
2bb70 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
2bb80 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
2bb90 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2bba0 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
2bbb0 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20  tively. ^The.** 
2bbc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
2bbd0 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51  ight also be [SQ
2bbe0 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69  LITE_UTF16] to i
2bbf0 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65  ndicate that the
2bc00 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65   routine.** expe
2bc10 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2bc20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  be UTF-16 string
2bc30 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  s in the native 
2bc40 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74  byte order, or t
2bc50 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63  he.** argument c
2bc60 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  an be [SQLITE_UT
2bc70 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20  F16_ALIGNED] if 
2bc80 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  the.** the routi
2bc90 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
2bca0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
2bcb0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
2bcc0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
2bcd0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2bce0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
2bcf0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
2bd00 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
2bd10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
2bd20 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
2bd30 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
2bd40 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
2bd50 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
2bd60 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
2bd70 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
2bd80 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
2bd90 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
2bda0 61 6c 6c 20 69 74 20 61 6e 79 20 6d 6f 72 65 29  all it any more)
2bdb0 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d 65 20  ..** ^Each time 
2bdc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2bdd0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
2bde0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
2bdf0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73   is passed.** as
2be00 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2be10 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74  eter a copy of t
2be20 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
2be30 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
2be40 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2be50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2be60 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ation() or sqlit
2be70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2be80 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ion16()..**.** ^
2be90 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
2bea0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61  guments to the a
2beb0 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
2bec0 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
2bed0 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
2bee0 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
2bef0 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64   by a (length, d
2bf00 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e  ata) pair and en
2bf10 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
2bf20 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
2bf30 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2bf40 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
2bf50 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
2bf60 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
2bf70 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 20 54  * registered.  T
2bf80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2bf90 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2bfa0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
2bfb0 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
2bfc0 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
2bfd0 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
2bfe0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
2bff0 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
2c000 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
2c010 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
2c020 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
2c030 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
2c040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c050 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2c060 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
2c070 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
2c080 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
2c090 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
2c0a0 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
2c0b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2c0c0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2c0d0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
2c0e0 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65 73 74  tion.  ^The dest
2c0f0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2c100 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2c110 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
2c120 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
2c130 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
2c140 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2c150 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
2c160 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
2c170 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c180 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  n_v2()..** ^Coll
2c190 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
2c1a0 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
2c1b0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
2c1c0 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
2c1d0 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
2c1e0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
2c1f0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
2c200 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c210 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
2c220 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2c230 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2c240 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
2c250 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2c260 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
2c270 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c280 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
2c290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2c2a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
2c2b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2c2c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2c2d0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2c2e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2c2f0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2c300 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2c310 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2c320 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2c330 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c340 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2c350 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2c360 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2c370 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2c380 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
2c390 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2c3a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2c3b0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
2c3c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2c3d0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
2c3e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c3f0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
2c400 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
2c410 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
2c420 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2c430 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2c440 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2c450 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2c460 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2c470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c480 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
2c490 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
2c4a0 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
2c4b0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
2c4c0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
2c4d0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
2c4e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
2c4f0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
2c500 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
2c510 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
2c520 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
2c530 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2c540 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
2c550 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2c560 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
2c570 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2c580 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
2c590 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
2c5a0 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
2c5b0 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
2c5c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c5d0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
2c5e0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
2c5f0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
2c600 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2c610 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
2c620 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
2c630 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
2c640 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
2c650 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
2c660 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
2c670 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
2c680 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
2c690 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
2c6a0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
2c6b0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
2c6c0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
2c6d0 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
2c6e0 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
2c6f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
2c700 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
2c710 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
2c720 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2c730 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
2c740 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
2c750 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
2c760 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c770 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
2c780 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c790 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
2c7a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c7b0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
2c7c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2c7d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
2c7e0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2c7f0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2c800 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2c810 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2c820 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
2c830 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
2c840 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2c850 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2c860 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
2c870 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
2c880 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c890 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2c8a0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
2c8b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2c8c0 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
2c8d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2c8e0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
2c8f0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
2c900 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
2c910 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2c920 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
2c930 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c940 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
2c950 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
2c960 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2c970 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
2c980 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2c990 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2c9a0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2c9b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2c9c0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2c9d0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2c9e0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2c9f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ca00 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2ca10 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2ca20 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2ca30 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2ca40 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2ca50 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
2ca60 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
2ca70 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
2ca80 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
2ca90 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
2caa0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
2cab0 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
2cac0 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
2cad0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
2cae0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2caf0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2cb00 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2cb10 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2cb20 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2cb30 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2cb40 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
2cb50 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2cb60 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2cb70 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2cb80 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2cb90 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2cba0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
2cbb0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
2cbc0 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
2cbd0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2cbe0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
2cbf0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
2cc00 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
2cc10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
2cc20 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
2cc30 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
2cc40 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
2cc50 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
2cc60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
2cc70 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2cc80 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2cc90 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2cca0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2ccb0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2ccc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
2ccd0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2cce0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2ccf0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2cd00 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2cd10 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2cd20 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2cd30 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
2cd40 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
2cd50 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
2cd60 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
2cd70 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
2cd80 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2cd90 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2cda0 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
2cdb0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
2cdc0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
2cdd0 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
2cde0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
2cdf0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
2ce00 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
2ce10 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
2ce20 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
2ce30 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
2ce40 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
2ce50 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
2ce60 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
2ce70 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
2ce80 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
2ce90 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
2cea0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2ceb0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2cec0 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
2ced0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
2cee0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
2cef0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
2cf00 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
2cf10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
2cf20 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
2cf30 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
2cf40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cf50 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2cf60 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2cf70 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2cf80 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2cf90 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2cfa0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2cfb0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2cfc0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2cfd0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
2cfe0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
2cff0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
2d000 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
2d010 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
2d020 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
2d030 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
2d040 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
2d050 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
2d060 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
2d070 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d  second. ^The num
2d080 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2d090 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2d0a0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
2d0b0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
2d0c0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
2d0d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2d0e0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
2d0f0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
2d100 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
2d110 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
2d120 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
2d130 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
2d140 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
2d150 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2d160 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d170 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
2d180 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
2d190 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
2d1a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
2d1b0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2d1c0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2d1d0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2d1e0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2d1f0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
2d200 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
2d210 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
2d220 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
2d230 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
2d240 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
2d250 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
2d260 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
2d270 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
2d280 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
2d290 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
2d2a0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
2d2b0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2d2c0 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
2d2d0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
2d2e0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
2d2f0 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
2d300 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
2d310 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2d320 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2d330 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
2d340 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
2d350 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
2d360 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
2d370 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2d380 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2d390 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
2d3a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d3b0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
2d3c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d3d0 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
2d3e0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
2d3f0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
2d400 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
2d410 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
2d420 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
2d430 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
2d440 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
2d450 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
2d460 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
2d470 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
2d480 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2d490 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
2d4a0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
2d4b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
2d4c0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2d4d0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
2d4e0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2d4f0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
2d500 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
2d510 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2d520 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2d530 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
2d540 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
2d550 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2d560 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
2d570 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
2d580 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
2d590 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2d5a0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
2d5b0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
2d5c0 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
2d5d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
2d5e0 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
2d5f0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
2d600 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
2d610 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2d620 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
2d630 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
2d640 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
2d650 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
2d660 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
2d670 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
2d680 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
2d690 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2d6a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2d6b0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
2d6c0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
2d6d0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2d6e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
2d6f0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2d700 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
2d710 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
2d720 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
2d730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2d740 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
2d750 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
2d760 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
2d770 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
2d780 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2d790 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
2d7a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
2d7b0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
2d7c0 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
2d7d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d7e0 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
2d7f0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
2d800 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
2d810 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
2d820 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
2d830 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
2d840 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2d850 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
2d860 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
2d870 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2d880 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
2d890 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
2d8a0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
2d8b0 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
2d8c0 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
2d8d0 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
2d8e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
2d8f0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
2d900 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
2d910 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
2d920 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
2d930 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
2d940 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2d950 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
2d960 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
2d970 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
2d980 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
2d990 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
2d9a0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
2d9b0 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
2d9c0 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
2d9d0 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
2d9e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2d9f0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
2da00 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
2da10 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
2da20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
2da30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
2da40 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
2da50 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
2da60 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
2da70 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2da80 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
2da90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2daa0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
2dab0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2dac0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2dad0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
2dae0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
2daf0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
2db00 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
2db10 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
2db20 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
2db30 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2db40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
2db50 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
2db60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
2db70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2db80 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
2db90 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
2dba0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
2dbb0 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
2dbc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dbd0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
2dbe0 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
2dbf0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
2dc00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2dc10 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
2dc20 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2dc30 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
2dc40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dc50 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
2dc60 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
2dc70 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
2dc80 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
2dc90 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
2dca0 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
2dcb0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
2dcc0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2dcd0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2dce0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
2dcf0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
2dd00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
2dd10 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2dd20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2dd30 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
2dd40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dd50 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
2dd60 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
2dd70 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2dd80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
2dd90 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e    ^If pStmt is N
2dda0 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
2ddb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ddc0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ddd0 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
2dde0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2ddf0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2de00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de10 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49  nection pDb.  ^I
2de20 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
2de30 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
2de40 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
2de50 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
2de60 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
2de70 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
2de80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2de90 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
2dea0 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
2deb0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2dec0 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
2ded0 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
2dee0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2def0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
2df00 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
2df10 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
2df20 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  er..*/.sqlite3_s
2df30 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
2df40 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
2df50 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
2df60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2df70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
2df80 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
2df90 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2dfa0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2dfb0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2dfc0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2dfd0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2dfe0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
2dff0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
2e000 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
2e010 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d  saction is [COMM
2e020 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e  IT | committed].
2e030 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2e040 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2e050 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2e060 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2e070 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2e080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e090 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2e0a0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  den..** ^The sql
2e0b0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2e0c0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2e0d0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2e0e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2e0f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2e100 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2e110 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43  tion is [ROLLBAC
2e120 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d  K | rolled back]
2e130 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2e140 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2e150 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2e160 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2e170 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
2e180 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2e190 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
2e1a0 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
2e1b0 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
2e1c0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
2e1d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
2e1e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
2e1f0 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
2e200 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
2e210 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2e220 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
2e230 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
2e240 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
2e250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e260 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e270 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69  (D,C,P) and sqli
2e280 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2e290 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
2e2a0 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  ns.** return the
2e2b0 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
2e2c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2e2d0 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ll of the same f
2e2e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68  unction.** on th
2e2f0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2e300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
2e310 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
2e320 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f  he first call fo
2e330 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20  r each function 
2e340 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on D..**.** The 
2e350 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
2e360 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2e370 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2e380 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2e390 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2e3a0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2e3b0 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
2e3c0 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
2e3d0 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
2e3e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e3f0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
2e400 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
2e410 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
2e420 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
2e430 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2e440 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
2e450 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
2e460 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
2e470 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2e480 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
2e490 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e4a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2e4b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2e4c0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2e4d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2e4e0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2e4f0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2e500 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2e510 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  raph..**.** ^Reg
2e520 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
2e530 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2e540 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
2e550 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  **.** ^When the 
2e560 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
2e570 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74  back routine ret
2e580 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b  urns zero, the [
2e590 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61  COMMIT].** opera
2e5a0 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20  tion is allowed 
2e5b0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d  to continue norm
2e5c0 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63  ally.  ^If the c
2e5d0 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65  ommit hook.** re
2e5e0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
2e5f0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54  then the [COMMIT
2e600 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  ] is converted i
2e610 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  nto a [ROLLBACK]
2e620 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
2e630 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
2e640 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
2e650 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
2e660 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
2e670 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
2e680 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
2e690 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
2e6a0 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
2e6b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  ack..**.** ^For 
2e6c0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2e6d0 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2e6e0 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2e6f0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
2e700 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
2e710 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
2e720 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
2e730 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
2e740 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
2e750 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
2e760 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
2e770 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
2e780 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
2e790 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
2e7a0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
2e7b0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
2e7c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2e7d0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2e7e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2e7f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
2e800 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  sed..**.** See a
2e810 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
2e820 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20  _update_hook()] 
2e830 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f  interface..*/.vo
2e840 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
2e850 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
2e860 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
2e870 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
2e880 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2e890 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
2e8a0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
2e8b0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
2e8c0 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
2e8d0 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
2e8e0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2e8f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
2e900 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
2e910 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2e920 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2e930 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
2e940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e950 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
2e960 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
2e970 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
2e980 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2e990 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
2e9a0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
2e9b0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  deleted..** ^Any
2e9c0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2e9d0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2e9e0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2e9f0 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
2ea00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2ea10 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2ea20 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  den..**.** ^The 
2ea30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2ea40 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
2ea50 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
2ea60 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
2ea70 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2ea80 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2ea90 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  eted..** ^The fi
2eaa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2eab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2eac0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
2ead0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
2eae0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2eaf0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68  e_hook()..** ^Th
2eb00 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
2eb10 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
2eb20 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
2eb30 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
2eb40 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
2eb50 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
2eb60 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
2eb70 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
2eb80 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
2eb90 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
2eba0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  ed..** ^The thir
2ebb0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
2ebc0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
2ebd0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
2ebe0 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
2ebf0 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
2ec00 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
2ec10 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
2ec20 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66  d row..** ^The f
2ec30 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
2ec40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2ec50 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f  rowid] of the ro
2ec60 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61  w..** ^In the ca
2ec70 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2ec80 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2ec90 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2eca0 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2ecb0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75  e..**.** ^(The u
2ecc0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
2ecd0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
2ece0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
2ecf0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
2ed00 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
2ed10 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
2ed20 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29  lite_sequence).)
2ed30 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ^.**.** ^In the 
2ed40 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
2ed50 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61  tation, the upda
2ed60 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f  te hook.** is no
2ed70 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64  t invoked when d
2ed80 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20  uplication rows 
2ed90 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61  are deleted beca
2eda0 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e  use of an.** [ON
2edb0 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43   CONFLICT | ON C
2edc0 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d  ONFLICT REPLACE]
2edd0 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69   clause.  ^Nor i
2ede0 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
2edf0 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
2ee00 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2ee10 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
2ee20 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
2ee30 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
2ee40 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
2ee50 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2ee60 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
2ee70 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
2ee80 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
2ee90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2eea0 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
2eeb0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2eec0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2eed0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2eee0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2eef0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2ef00 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
2ef10 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
2ef20 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2ef30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2ef40 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2ef50 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2ef60 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2ef70 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2ef80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2ef90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2efa0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2efb0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
2efc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2efd0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2efe0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2eff0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2f000 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f010 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2f020 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2f030 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2f040 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  aph..**.** ^The 
2f050 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2f060 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
2f070 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ion.** returns t
2f080 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
2f090 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2f0a0 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  call.** on the s
2f0b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2f0c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
2f0d0 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
2f0e0 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e  first call on D.
2f0f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
2f100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
2f110 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
2f120 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2f130 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
2f140 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64  erfaces..*/.void
2f150 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   *sqlite3_update
2f160 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33  _hook(.  sqlite3
2f170 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2f180 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63  id *,int ,char c
2f190 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73  onst *,char cons
2f1a0 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  t *,sqlite3_int6
2f1b0 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a  4),.  void*.);..
2f1c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f1d0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
2f1e0 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
2f1f0 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ache.** KEYWORDS
2f200 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
2f210 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2f220 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
2f230 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
2f240 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
2f250 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
2f260 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
2f270 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
2f280 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
2f290 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
2f2a0 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
2f2b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
2f2c0 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
2f2d0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2f2e0 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
2f2f0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
2f300 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
2f310 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63  se.)^.**.** ^Cac
2f320 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
2f330 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
2f340 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
2f350 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
2f360 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
2f370 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
2f380 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
2f390 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
2f3a0 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
2f3b0 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
2f3c0 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
2f3d0 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
2f3e0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tely..**.** ^(Th
2f3f0 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
2f400 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
2f410 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
2f420 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
2f430 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
2f440 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2f450 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2f460 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2f470 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
2f480 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
2f490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
2f4a0 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
2f4b0 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
2f4c0 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
2f4d0 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
2f4e0 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29  ey were opened.)
2f4f0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ^.**.** ^(This r
2f500 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
2f510 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
2f520 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
2f530 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
2f540 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ed.** successful
2f550 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
2f560 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2f570 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a   otherwise.)^.**
2f580 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68  .** ^Shared cach
2f590 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2f5a0 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
2f5b0 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
2f5c0 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
2f5d0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2f5e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2f5f0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
2f600 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
2f610 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
2f620 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
2f630 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
2f640 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
2f650 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a  -Cache Mode].*/.
2f660 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
2f670 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
2f680 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2f690 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
2f6a0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
2f6b0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
2f6c0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2f6d0 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
2f6e0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
2f6f0 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
2f700 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
2f710 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
2f720 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2f730 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
2f740 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
2f750 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
2f760 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
2f770 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
2f780 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
2f790 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
2f7a0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
2f7b0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2f7c0 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
2f7d0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2f7e0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
2f7f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
2f800 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
2f810 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
2f820 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
2f830 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
2f840 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  uested..** ^The 
2f850 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2f860 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65  memory() routine
2f870 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75   is a no-op retu
2f880 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66  rning zero.** if
2f890 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63   SQLite is not c
2f8a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
2f8b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
2f8c0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
2f8d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2f8e0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2f8f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f900 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2f910 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2f920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f930 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2f940 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2f950 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2f960 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2f970 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2f980 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2f990 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2f9a0 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2f9b0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2f9c0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2f9d0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2f9e0 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2f9f0 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2fa00 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2fa10 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2fa20 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2fa30 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2fa40 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2fa50 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2fa60 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2fa70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2fa80 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2fa90 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2faa0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2fab0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2fac0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2fad0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2fae0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2faf0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2fb00 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2fb10 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2fb20 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2fb30 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2fb40 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2fb50 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2fb60 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2fb70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2fb80 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2fb90 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2fba0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2fbb0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2fbc0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2fbd0 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2fbe0 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2fbf0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2fc00 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2fc10 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2fc20 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2fc30 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2fc40 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2fc50 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2fc60 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2fc70 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2fc80 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2fc90 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2fca0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2fcb0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2fcc0 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2fcd0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2fce0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2fcf0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2fd00 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2fd10 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2fd20 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2fd30 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2fd40 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2fd50 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2fd60 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2fd70 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2fd80 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2fd90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2fda0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2fdb0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2fdc0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2fdd0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2fde0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2fdf0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2fe00 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2fe10 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2fe20 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2fe30 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2fe40 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2fe50 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2fe60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2fe70 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2fe80 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2fe90 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2fea0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2feb0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2fec0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2fed0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2fee0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2fef0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2ff00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ff10 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2ff20 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2ff30 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2ff40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2ff50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2ff60 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2ff70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2ff80 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2ff90 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2ffa0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2ffb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ffc0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2ffd0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2ffe0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2fff0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30000 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
30010 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
30020 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
30030 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
30040 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
30050 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
30060 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30070 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
30080 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
30090 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
300a0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
300b0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
300c0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
300d0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
300e0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
300f0 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
30100 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
30110 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
30120 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
30130 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
30140 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
30150 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
30160 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
30170 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
30180 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
30190 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
301a0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
301b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
301c0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
301d0 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
301e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
301f0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
30200 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
30210 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
30220 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
30230 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
30240 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
30250 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
30260 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
30270 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
30280 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
30290 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
302a0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
302b0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
302c0 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
302d0 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
302e0 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
302f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
30300 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
30310 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
30320 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
30330 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
30340 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
30350 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
30360 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
30370 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
30380 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
30390 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
303a0 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
303b0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
303c0 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
303d0 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
303e0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
303f0 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
30400 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
30410 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
30420 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
30430 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
30440 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
30450 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
30460 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
30470 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
30480 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
30490 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
304a0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
304b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
304c0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
304d0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
304e0 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
304f0 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
30500 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
30510 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
30520 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
30530 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
30540 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
30550 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
30560 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
30570 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
30580 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
30590 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
305a0 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
305b0 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
305c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
305d0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
305e0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
305f0 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
30600 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
30610 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
30620 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
30630 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
30640 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
30650 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
30660 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
30670 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
30680 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
30690 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
306a0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
306b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
306c0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
306d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
306e0 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
306f0 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
30700 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
30710 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
30720 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
30730 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
30740 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
30750 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
30760 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
30770 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
30780 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
30790 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
307a0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
307b0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
307c0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
307d0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
307e0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
307f0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
30800 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
30810 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
30820 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
30830 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
30840 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
30850 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
30860 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
30870 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
30880 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
30890 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
308a0 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
308b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
308c0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
308d0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
308e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
308f0 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
30900 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
30910 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
30920 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
30930 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
30940 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
30950 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
30960 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
30970 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
30980 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
30990 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
309a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
309b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
309c0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
309d0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
309e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
309f0 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
30a00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
30a10 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
30a20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
30a30 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
30a40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
30a50 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
30a60 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
30a70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
30a80 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
30a90 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
30aa0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
30ab0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
30ac0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
30ad0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
30ae0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
30af0 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
30b00 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
30b10 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
30b20 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
30b30 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
30b40 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
30b50 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
30b60 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
30b70 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
30b80 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
30b90 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
30ba0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
30bb0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
30bc0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
30bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
30be0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
30bf0 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
30c00 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
30c10 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
30c20 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
30c30 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
30c40 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
30c50 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
30c60 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
30c70 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
30c80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
30c90 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
30ca0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
30cb0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
30cc0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
30cd0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
30ce0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
30cf0 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
30d00 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
30d10 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
30d20 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
30d30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
30d40 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
30d50 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
30d60 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
30d70 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
30d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
30d90 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
30da0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30db0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
30dc0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
30dd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
30de0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
30df0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
30e00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
30e10 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
30e20 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
30e30 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
30e40 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
30e50 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
30e60 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
30e70 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
30e80 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30e90 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
30ea0 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
30eb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
30ec0 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
30ed0 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
30ee0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
30ef0 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
30f00 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
30f10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
30f20 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
30f30 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
30f40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
30f50 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
30f60 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
30f70 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
30f80 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
30f90 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
30fa0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30fb0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
30fc0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
30fd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
30fe0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
30ff0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
31000 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31010 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
31020 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
31030 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
31040 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
31050 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
31060 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
31070 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
31080 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
31090 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
310a0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
310b0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
310c0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
310d0 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
310e0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
310f0 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
31100 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
31110 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
31120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31130 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
31140 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
31150 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
31160 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
31170 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
31180 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
31190 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
311a0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
311b0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
311c0 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
311d0 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
311e0 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
311f0 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
31200 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
31210 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
31220 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
31230 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
31240 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
31250 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
31260 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
31270 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
31280 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
31290 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
312a0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
312b0 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
312c0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
312d0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
312e0 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
312f0 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
31300 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
31310 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
31320 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
31330 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
31340 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
31350 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
31360 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
31370 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
31380 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
31390 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
313a0 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
313b0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
313c0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
313d0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
313e0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
313f0 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
31400 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
31410 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
31420 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
31430 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
31440 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
31450 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
31460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31470 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
31480 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
31490 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
314a0 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
314b0 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
314c0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
314d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
314e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
314f0 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
31500 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
31510 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
31520 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
31530 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
31540 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
31550 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
31560 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
31570 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
31580 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
31590 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
315a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
315b0 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
315c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
315d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
315e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
315f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
31600 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
31610 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
31620 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
31630 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
31640 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
31650 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
31660 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
31670 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
31680 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
31690 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
316a0 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
316b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
316c0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
316d0 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
316e0 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
316f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
31700 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
31710 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
31720 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
31730 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
31740 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
31750 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
31760 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
31770 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
31780 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
31790 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
317a0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
317b0 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
317c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
317d0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
317e0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
317f0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
31800 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
31810 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
31820 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
31830 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
31840 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
31850 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
31860 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
31870 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
31880 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
31890 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
318a0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
318b0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
318c0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
318d0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
318e0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
318f0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
31900 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
31910 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
31920 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
31930 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
31940 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
31950 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
31960 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
31970 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
31980 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
31990 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
319a0 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
319b0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
319c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
319d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
319e0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
319f0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
31a00 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
31a10 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
31a20 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
31a30 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
31a40 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
31a50 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
31a60 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
31a70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
31a80 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
31a90 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
31aa0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
31ab0 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
31ac0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
31ad0 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
31ae0 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
31af0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
31b00 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
31b10 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
31b20 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
31b30 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
31b40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31b50 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
31b60 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
31b70 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
31b80 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
31b90 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
31ba0 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69  ule..**.** ^A vi
31bb0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31bc0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
31bd0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
31be0 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
31bf0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
31c00 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
31c10 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
31c20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
31c30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31c40 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
31c50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31c60 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
31c70 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74  * ^The registrat
31c80 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
31c90 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
31ca0 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
31cb0 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
31cc0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
31cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31ce0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
31cf0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
31d00 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
31d10 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
31d20 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
31d30 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
31d40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31d50 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
31d60 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
31d70 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
31d80 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
31d90 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
31da0 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
31db0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
31dc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
31dd0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
31de0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
31df0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
31e00 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
31e10 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
31e20 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
31e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
31e40 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
31e50 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
31e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
31e70 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
31e80 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
31e90 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
31ea0 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
31eb0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
31ec0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
31ed0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
31ee0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
31ef0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
31f00 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
31f10 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31f20 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
31f30 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31f40 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
31f50 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
31f60 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
31f70 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
31f80 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
31f90 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
31fa0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31fb0 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
31fc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
31fd0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
31fe0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
31ff0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
32000 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
32010 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
32020 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
32030 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
32040 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
32050 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
32060 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
32070 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
32080 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
32090 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
320a0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
320b0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
320c0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
320d0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
320e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
320f0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
32100 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
32110 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
32120 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
32130 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
32140 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
32150 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
32160 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
32170 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
32180 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
32190 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
321a0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
321b0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
321c0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
321d0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
321e0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
321f0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
32200 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32210 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
32220 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32230 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32240 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
32250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32260 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
32270 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
32280 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32290 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
322a0 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
322b0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
322c0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
322d0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
322e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
322f0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
32300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32310 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
32320 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
32330 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
32340 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f  sed as part.** o
32350 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
32360 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20  able] interface 
32370 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
32380 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
32390 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
323a0 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
323b0 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
323c0 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
323d0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
323e0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
323f0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
32400 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
32410 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
32420 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
32430 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
32440 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
32450 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
32460 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
32470 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
32480 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
32490 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
324a0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
324b0 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
324c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63  ** <blockquote>c
324d0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62  olumn OP expr</b
324e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
324f0 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
32500 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
32510 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20  ;, or &gt;=.)^  
32520 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  ^(The particular
32530 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
32540 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
32550 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67  raint[].op using
32560 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   one of the.** [
32570 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
32580 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c  STRAINT_EQ | SQL
32590 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
325a0 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e  AINT_ values].)^
325b0 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20  .** ^(The index 
325c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
325d0 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
325e0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
325f0 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
32600 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
32610 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
32620 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
32630 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
32640 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
32650 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
32660 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
32670 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
32680 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
32690 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
326a0 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
326b0 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
326c0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
326d0 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
326e0 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
326f0 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
32700 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
32710 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
32720 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
32730 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
32740 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
32750 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
32760 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
32770 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
32780 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
32790 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
327a0 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61  use terms that a
327b0 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74  re.** relevant t
327c0 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
327d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
327e0 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
327f0 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e  .** ^Information
32800 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
32810 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
32820 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
32830 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72  []..** ^Each ter
32840 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
32850 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
32860 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
32870 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
32880 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65   [xBestIndex] me
32890 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
328a0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
328b0 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
328c0 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
328d0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
328e0 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
328f0 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30   ^If argvIndex>0
32900 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
32910 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
32920 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32930 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
32940 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
32950 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
32960 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
32970 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49  ry in argv.  ^(I
32980 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
32990 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
329a0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
329b0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
329c0 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
329d0 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
329e0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
329f0 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
32a00 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
32a10 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ite.)^.**.** ^Th
32a20 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
32a30 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
32a40 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
32a50 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
32a60 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
32a70 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72  .** ^[sqlite3_fr
32a80 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
32a90 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
32aa0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e  and only if.** n
32ab0 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
32ac0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e  is true..**.** ^
32ad0 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
32ae0 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
32af0 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
32b00 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
32b10 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
32b20 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
32b30 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
32b40 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
32b50 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
32b60 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
32b70 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
32b80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d  **.** ^The estim
32b90 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
32ba0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
32bb0 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
32bc0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
32bd0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
32be0 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
32bf0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
32c00 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
32c10 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
32c20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
32c30 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
32c40 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
32c50 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
32c60 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
32c70 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
32c80 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
32c90 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
32ca0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
32cb0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
32cc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
32cd0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
32ce0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
32cf0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32d00 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
32d10 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
32d20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32d30 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
32d40 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
32d50 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
32d60 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
32d70 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
32d80 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
32d90 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
32da0 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
32db0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
32dc0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
32dd0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
32de0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
32df0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
32e00 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
32e10 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
32e20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
32e30 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
32e40 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
32e50 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
32e60 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
32e70 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
32e80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
32e90 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
32ea0 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
32eb0 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
32ec0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
32ed0 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
32ee0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
32ef0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
32f00 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
32f10 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
32f20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
32f30 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
32f40 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
32f50 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
32f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32f70 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
32f80 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
32f90 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
32fa0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
32fb0 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
32fc0 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
32fd0 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
32fe0 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
32ff0 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
33000 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
33010 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
33020 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
33030 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
33040 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
33050 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
33060 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
33070 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
33080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33090 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
330a0 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
330b0 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
330c0 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
330d0 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
330e0 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
330f0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
33100 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
33110 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
33120 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
33130 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
33140 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
33150 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
33160 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
33170 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
33180 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
33190 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
331a0 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
331b0 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
331c0 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
331d0 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
331e0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
331f0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
33200 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65  e Constraint Ope
33210 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a  rator Codes.**.*
33220 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64  * These macros d
33230 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77  efined the allow
33240 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  ed values for th
33250 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  e.** [sqlite3_in
33260 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74  dex_info].aConst
33270 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64  raint[].op field
33280 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65  .  Each value re
33290 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f  presents.** an o
332a0 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20  perator that is 
332b0 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72  part of a constr
332c0 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65  aint term in the
332d0 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66   wHERE clause of
332e0 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74  .** a query that
332f0 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c   uses a [virtual
33300 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66   table]..*/.#def
33310 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
33320 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
33330 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
33340 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
33350 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
33360 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
33370 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
33380 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
33390 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
333a0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
333b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
333c0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
333d0 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
333e0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
333f0 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
33400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33410 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
33420 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
33430 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  ntation.**.** ^T
33440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33450 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  e used to regist
33460 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  er a new [virtua
33470 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
33480 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65  name..** ^Module
33490 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must be r
334a0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65  egistered before
334b0 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e  .** creating a n
334c0 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
334d0 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64  e] using the mod
334e0 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75  ule and before u
334f0 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69  sing a.** preexi
33500 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74  sting [virtual t
33510 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  able] for the mo
33520 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dule..**.** ^The
33530 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20   module name is 
33540 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68  registered on th
33550 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33560 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
33570 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
33580 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  t parameter.  ^T
33590 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
335a0 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
335b0 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
335c0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
335d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
335e0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
335f0 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  o.** the impleme
33600 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ntation of the [
33610 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33620 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f  dule].   ^The fo
33630 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  urth.** paramete
33640 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
33650 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f  y client data po
33660 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
33670 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
33680 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74  into the [xCreat
33690 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
336a0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  ] methods of the
336b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
336c0 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20  odule.** when a 
336d0 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
336e0 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72  e is be being cr
336f0 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69  eated or reiniti
33700 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  alized..**.** ^T
33710 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
33720 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e  e_module_v2() in
33730 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69  terface has a fi
33740 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68  fth parameter wh
33750 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
33760 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
33770 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69  tor for the pCli
33780 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74  entData.  ^SQLit
33790 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65  e will.** invoke
337a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
337b0 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20  function (if it 
337c0 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65  is not NULL) whe
337d0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c  n SQLite.** no l
337e0 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20  onger needs the 
337f0 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e  pClientData poin
33800 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ter.  ^The sqlit
33810 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
33820 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
33830 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
33840 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33850 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68  module_v2() with
33860 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72   a NULL.** destr
33870 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  uctor..*/.int sq
33880 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
33890 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ule(.  sqlite3 *
338a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
338b0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
338c0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
338d0 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
338e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
338f0 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
33900 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
33910 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
33920 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
33930 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
33940 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
33950 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
33960 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f  tData          /
33970 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
33980 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
33990 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ct */.);.int sql
339a0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
339b0 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
339c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
339d0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
339e0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
339f0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
33a00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33a10 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
33a20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
33a30 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
33a40 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
33a50 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
33a60 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
33a70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
33a80 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20  entData,        
33a90 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
33aa0 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
33ab0 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
33ac0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
33ad0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
33ae0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
33af0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
33b00 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
33b10 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65  l Table Instance
33b20 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
33b30 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
33b40 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  b.**.** Every [v
33b50 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33b60 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
33b70 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
33b80 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f  ass.** of this o
33b90 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69 62  bject to describ
33ba0 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
33bb0 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68  nstance.** of th
33bc0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
33bd0 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  ].  Each subclas
33be0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
33bf0 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
33c00 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
33c10 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
33c20 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
33c30 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
33c40 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
33c50 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
33c60 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
33c70 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
33c80 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
33c90 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
33ca0 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  ^Virtual tables 
33cb0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
33cc0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
33cd0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
33ce0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
33cf0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
33d00 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a  _mprintf()] to z
33d10 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74  ErrMsg.  The met
33d20 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61  hod should.** ta
33d30 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79  ke care that any
33d40 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73   prior string is
33d50 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c   freed by a call
33d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
33d70 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  e()].** prior to
33d80 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77   assigning a new
33d90 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d   string to zErrM
33da0 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20  sg.  ^After the 
33db0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
33dc0 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
33dd0 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
33de0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
33df0 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
33e00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
33e10 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
33e20 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
33e30 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
33e40 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f  ll be zeroed..*/
33e50 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
33e60 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
33e70 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
33e80 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
33e90 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
33ea0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
33eb0 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
33ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33ed0 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20     /* NO LONGER 
33ee0 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a  USED */.  char *
33ef0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
33f00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
33f10 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
33f20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
33f30 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
33f40 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
33f50 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
33f60 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
33f70 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
33f80 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33f90 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
33fa0 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a  e Cursor Object.
33fb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
33fc0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
33fd0 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
33fe0 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76  cursor}.**.** Ev
33ff0 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
34000 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
34010 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
34020 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
34030 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  .** following st
34040 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72  ructure to descr
34050 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
34060 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a   point into the.
34070 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
34080 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  e] and are used.
34090 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
340a0 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
340b0 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
340c0 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
340d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
340e0 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20  _module.xOpen | 
340f0 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  xOpen] method of
34100 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
34110 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a  are destroyed.**
34120 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
34130 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c  _module.xClose |
34140 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e   xClose] method.
34150 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 75 73    Cursors are us
34160 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46  ed.** by the [xF
34170 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c  ilter], [xNext],
34180 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d   [xEof], [xColum
34190 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d  n], and [xRowid]
341a0 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74   methods.** of t
341b0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
341c0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
341d0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69  tation will defi
341e0 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  ne.** the conten
341f0 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74  t of a cursor st
34200 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20  ructure to suit 
34210 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a  its own needs..*
34220 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63  *.** This superc
34230 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f  lass exists in o
34240 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66  rder to define f
34250 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72  ields of the cur
34260 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  sor that.** are 
34270 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d  common to all im
34280 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
34290 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
342a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20  _vtab_cursor {. 
342b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70   sqlite3_vtab *p
342c0 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69  Vtab;      /* Vi
342d0 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74  rtual table of t
342e0 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20  his cursor */.  
342f0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
34300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34310 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
34320 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
34330 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
34340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
34350 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20  lare The Schema 
34360 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  Of A Virtual Tab
34370 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78  le.**.** ^The [x
34380 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
34390 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
343a0 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  f a.** [virtual 
343b0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61  table module] ca
343c0 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ll this interfac
343d0 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20  e.** to declare 
343e0 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20  the format (the 
343f0 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
34400 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  pes of the colum
34410 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69  ns) of.** the vi
34420 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65  rtual tables the
34430 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a  y implement..*/.
34440 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
34450 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
34460 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
34470 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  SQL);../*.** CAP
34480 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
34490 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
344a0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
344b0 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74  *.** ^(Virtual t
344c0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
344d0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
344e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
344f0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
34500 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75  ing the [xFindFu
34510 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f  nction] method o
34520 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
34530 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a  able module].  .
34540 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  ** But global ve
34550 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
34560 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
34570 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
34580 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
34590 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
345a0 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
345b0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
345c0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
345d0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
345e0 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
345f0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
34600 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
34610 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
34620 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
34630 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
34640 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
34650 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29  ion is created.)
34660 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ^  ^The implemen
34670 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
34680 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
34690 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
346a0 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
346b0 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
346c0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
346d0 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
346e0 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
346f0 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
34700 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
34710 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66   a placeholder f
34720 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e  unction that can
34730 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a   be overloaded.*
34740 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20  * by a [virtual 
34750 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  table]..*/.int s
34760 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
34770 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
34780 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
34790 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
347a0 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
347b0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
347c0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
347d0 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
347e0 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
347f0 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
34800 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
34810 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
34820 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
34830 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
34840 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
34850 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
34860 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
34870 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
34880 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
34890 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
348a0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
348b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
348c0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
348d0 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
348e0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
348f0 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
34900 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
34910 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
34920 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
34930 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
34940 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
34950 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
34960 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
34970 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
34980 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  OB.** KEYWORDS: 
34990 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42  {BLOB handle} {B
349a0 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a  LOB handles}.**.
349b0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
349c0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
349d0 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
349e0 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a   BLOB on which.*
349f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
34a00 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
34a10 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e  al BLOB I/O] can
34a20 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   be performed..*
34a30 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  * ^Objects of th
34a40 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
34a50 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
34a60 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  blob_open()].** 
34a70 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
34a80 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34a90 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  lose()]..** ^The
34aa0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
34ab0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
34ac0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
34ad0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
34ae0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
34af0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
34b00 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
34b10 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e  f the BLOB..** ^
34b20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
34b30 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
34b40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
34b50 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34b60 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
34b70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
34b80 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
34b90 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
34ba0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
34bb0 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
34bc0 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
34bd0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
34be0 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
34bf0 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
34c00 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
34c10 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
34c20 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
34c30 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
34c40 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
34c50 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
34c60 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
34c70 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
34c80 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
34c90 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
34ca0 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
34cb0 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
34cc0 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
34cd0 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
34ce0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
34cf0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
34d00 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
34d10 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f  en the BLOB is o
34d20 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a  pened for read.*
34d30 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  * and write acce
34d40 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65  ss. ^If it is ze
34d50 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  ro, the BLOB is 
34d60 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
34d70 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69  access..** ^It i
34d80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
34d90 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
34da0 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
34db0 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d  an index or prim
34dc0 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20  ary .** key for 
34dd0 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f  writing. ^If [fo
34de0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
34df0 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c  aints] are enabl
34e00 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f  ed, it is .** no
34e10 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
34e20 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
34e30 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63   is part of a [c
34e40 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72  hild key] for wr
34e50 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  iting..**.** ^No
34e60 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61  te that the data
34e70 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74  base name is not
34e80 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68   the filename th
34e90 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  at contains.** t
34ea0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20  he database but 
34eb0 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f  rather the symbo
34ec0 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  lic name of the 
34ed0 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a  database that.**
34ee0 20 61 70 70 65 61 72 73 20 61 66 74 65 72 20 74   appears after t
34ef0 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68  he AS keyword wh
34f00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
34f10 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
34f20 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
34f30 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61  ^For the main da
34f40 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
34f50 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
34f60 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f  s "main"..** ^Fo
34f70 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  r TEMP tables, t
34f80 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
34f90 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
34fa0 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
34fb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
34fc0 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
34fd0 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
34fe0 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
34ff0 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
35000 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
35010 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
35020 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73  d and *ppBlob is
35030 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20   set.** to be a 
35040 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a  null pointer.)^.
35050 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
35060 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61  n sets the [data
35070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35080 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
35090 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73  message.** acces
350a0 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
350b0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e  e3_errcode()] an
350c0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
350d0 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64  g()] and related
350e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e  .** functions. ^
350f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a 70  Note that the *p
35100 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69  pBlob variable i
35110 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c  s always initial
35120 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79  ized in a.** way
35130 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73   that makes it s
35140 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73  afe to invoke [s
35150 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
35160 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a  e()] on *ppBlob.
35170 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
35180 20 74 68 65 20 73 75 63 63 65 73 73 20 6f 72 20   the success or 
35190 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20  failure of this 
351a0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e  routine..**.** ^
351b0 28 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74  (If the row that
351c0 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70   a BLOB handle p
351d0 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69  oints to is modi
351e0 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55  fied by an.** [U
351f0 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
35200 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46  , or by [ON CONF
35210 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63  LICT] side-effec
35220 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42  ts.** then the B
35230 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61  LOB handle is ma
35240 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64  rked as "expired
35250 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72  "..** This is tr
35260 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  ue if any column
35270 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63   of the row is c
35280 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63  hanged, even a c
35290 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74  olumn.** other t
352a0 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20  han the one the 
352b0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f  BLOB handle is o
352c0 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61  pen on.)^.** ^Ca
352d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
352e0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
352f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
35300 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61  rite()] for.** a
35310 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61   expired BLOB ha
35320 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61  ndle fail with a
35330 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  n return code of
35340 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
35350 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72  .** ^(Changes wr
35360 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
35370 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
35380 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
35390 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62   not.** rolled b
353a0 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72  ack by the expir
353b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f  ation of the BLO
353c0 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73  B.  Such changes
353d0 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
353e0 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68  .** commit if th
353f0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  e transaction co
35400 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
35410 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  etion.)^.**.** ^
35420 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
35430 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
35440 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65  nterface to dete
35450 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f  rmine the size o
35460 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20  f.** the opened 
35470 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65  blob.  ^The size
35480 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e   of a blob may n
35490 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ot be changed by
354a0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
354b0 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50  ce.  Use the [UP
354c0 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  DATE] SQL comman
354d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
354e0 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f  size of a.** blo
354f0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  b..**.** ^The [s
35500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
35510 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c  blob()] and [sql
35520 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
35530 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63  blob()] interfac
35540 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75  es.** and the bu
35550 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62  ilt-in [zeroblob
35560 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  ] SQL function c
35570 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64  an be used, if d
35580 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72  esired,.** to cr
35590 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a  eate an empty, z
355a0 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20  ero-filled blob 
355b0 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64  in which to read
355c0 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a   or write using.
355d0 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
355e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  e..**.** To avoi
355f0 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61  d a resource lea
35600 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42  k, every open [B
35610 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75  LOB handle] shou
35620 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ld eventually.**
35630 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20   be released by 
35640 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
35650 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
35660 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35670 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
35680 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
35690 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
356a0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
356b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
356c0 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
356d0 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
356e0 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
356f0 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
35700 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
35710 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
35720 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
35730 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e   ^Closes an open
35740 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
35750 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61  **.** ^Closing a
35760 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
35770 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
35780 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
35790 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
357a0 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
357b0 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
357c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
357d0 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
357e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
357f0 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
35800 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e  mmit mode]..** ^
35810 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
35820 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
35830 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
35840 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
35850 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
35860 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
35870 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a   they will fit..
35880 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20  **.** ^(Closing 
35890 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66  the BLOB often f
358a0 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65  orces the change
358b0 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b  s.** out to disk
358c0 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49   and so if any I
358d0 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c  /O errors occur,
358e0 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c   they will likel
358f0 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68  y occur.** at th
35900 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  e time when the 
35910 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20  BLOB is closed. 
35920 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74   Any errors that
35930 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a   occur during.**
35940 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70   closing are rep
35950 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a  orted as a non-z
35960 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ero return value
35970 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  .)^.**.** ^(The 
35980 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
35990 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
359a0 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
359b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
359c0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
359d0 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
359e0 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a  l closed.)^.**.*
359f0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
35a00 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e  routine with a n
35a10 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63  ull pointer (suc
35a20 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65  h as would be re
35a30 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66  turned.** by a f
35a40 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
35a50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
35a60 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
35a70 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
35a80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c   sqlite3_blob_cl
35a90 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ose(sqlite3_blob
35aa0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
35ab0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
35ac0 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e   Size Of An Open
35ad0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   BLOB.**.** ^Ret
35ae0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
35af0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
35b00 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
35b10 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
35b20 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
35b30 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
35b40 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
35b50 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65  .  ^The.** incre
35b60 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20  mental blob I/O 
35b70 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c  routines can onl
35b80 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72  y read or overwr
35b90 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a  iting existing.*
35ba0 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20  * blob content; 
35bb0 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e  they cannot chan
35bc0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
35bd0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   blob..**.** Thi
35be0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
35bf0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
35c00 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
35c10 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
35c20 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
35c30 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35c40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35c50 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
35c60 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
35c70 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
35c80 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
35c90 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
35ca0 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
35cb0 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
35cc0 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
35cd0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
35ce0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
35cf0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e   behavior..*/.in
35d00 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
35d10 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
35d20 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
35d30 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61  I3REF: Read Data
35d40 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
35d50 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
35d60 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
35d70 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64   is used to read
35d80 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70   data from an op
35d90 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
35da0 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65   into a.** calle
35db0 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
35dc0 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61  r. N bytes of da
35dd0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  ta are copied in
35de0 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66  to buffer Z.** f
35df0 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  rom the open BLO
35e00 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
35e10 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e  ffset iOffset.)^
35e20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  .**.** ^If offse
35e30 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
35e40 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
35e50 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
35e60 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
35e70 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
35e80 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
35e90 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66  ta is read.  ^If
35ea0 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73   N or iOffset is
35eb0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
35ec0 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ro, [SQLITE_ERRO
35ed0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
35ee0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
35ef0 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65  ad..** ^The size
35f00 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e   of the blob (an
35f10 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
35f20 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
35f30 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
35f40 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
35f50 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
35f60 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
35f70 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
35f80 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  An attempt to re
35f90 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72  ad from an expir
35fa0 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35fb0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
35fc0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
35fd0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
35fe0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
35ff0 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ss, sqlite3_blob
36000 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  _read() returns 
36010 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74  SQLITE_OK..** Ot
36020 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
36030 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
36040 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
36050 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
36060 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
36070 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
36080 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
36090 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
360a0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
360b0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
360c0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
360d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
360e0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
360f0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
36100 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
36110 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
36120 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
36130 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
36140 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
36150 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
36160 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
36170 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
36180 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
36190 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
361a0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a  _blob_write()]..
361b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
361c0 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
361d0 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
361e0 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
361f0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
36200 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61  PI3REF: Write Da
36210 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
36220 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
36230 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
36240 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
36250 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
36260 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
36270 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
36280 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
36290 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66  fer. ^N bytes of
362a0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
362b0 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
362c0 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f   Z.** into the o
362d0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
362e0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
362f0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  fset..**.** ^If 
36300 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
36310 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
36320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77  first argument w
36330 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
36340 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68  r.** writing (th
36350 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
36360 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  r to [sqlite3_bl
36370 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a  ob_open()] was z
36380 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75  ero),.** this fu
36390 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
363a0 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
363b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
363c0 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20  nction may only 
363d0 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65  modify the conte
363e0 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b  nts of the BLOB;
363f0 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f   it is.** not po
36400 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61  ssible to increa
36410 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  se the size of a
36420 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73   BLOB using this
36430 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66   API..** ^If off
36440 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
36450 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
36460 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
36470 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
36480 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
36490 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
364a0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
364b0 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65    ^If N is.** le
364c0 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
364d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
364e0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
364f0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
36500 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  ** The size of t
36510 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e  he BLOB (and hen
36520 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
36530 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
36540 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
36550 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
36560 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
36570 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
36580 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
36590 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74  tempt to write t
365a0 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  o an expired [BL
365b0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
365c0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
365d0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
365e0 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74  E_ABORT].  ^Writ
365f0 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74  es to the BLOB t
36600 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20  hat occurred.** 
36610 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42  before the [BLOB
36620 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64   handle] expired
36630 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20   are not rolled 
36640 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65  back by the.** e
36650 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
36660 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20   handle, though 
36670 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20  of course those 
36680 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a  changes might.**
36690 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77   have been overw
366a0 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74  ritten by the st
366b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70  atement that exp
366c0 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61  ired the BLOB ha
366d0 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74  ndle.** or by ot
366e0 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  her independent 
366f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
36700 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
36710 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
36720 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  te() returns SQL
36730 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
36740 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
36750 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
36760 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
36770 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
36780 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
36790 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
367a0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
367b0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
367c0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
367d0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
367e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
367f0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
36800 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
36810 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
36820 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
36830 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
36840 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
36850 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
36860 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
36870 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
36880 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
36890 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
368a0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
368b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
368c0 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a  lob_read()]..*/.
368d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
368e0 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
368f0 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
36900 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
36910 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
36920 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
36930 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
36940 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20  Objects.**.** A 
36950 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
36960 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
36970 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
36980 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
36990 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
369a0 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
369b0 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
369c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
369d0 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
369e0 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
369f0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
36a00 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
36a10 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
36a20 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
36a30 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
36a40 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
36a50 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
36a60 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
36a70 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
36a80 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
36a90 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
36aa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36ab0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
36ac0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36ad0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
36ae0 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
36af0 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20  ..** ^Names are 
36b00 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a  case sensitive..
36b10 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65  ** ^Names are ze
36b20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
36b30 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
36b40 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
36b50 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f  match, a NULL po
36b60 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
36b70 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61  d..** ^If zVfsNa
36b80 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
36b90 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
36ba0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
36bb0 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61 72  ** ^New VFSes ar
36bc0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
36bd0 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  h sqlite3_vfs_re
36be0 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61  gister()..** ^Ea
36bf0 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d  ch new VFS becom
36c00 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  es the default V
36c10 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66  FS if the makeDf
36c20 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a  lt flag is set..
36c30 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46 53  ** ^The same VFS
36c40 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
36c50 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
36c60 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79  s without injury
36c70 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e  ..** ^To make an
36c80 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e   existing VFS in
36c90 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  to the default V
36ca0 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20  FS, register it 
36cb0 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  again.** with th
36cc0 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
36cd0 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66  set.  If two dif
36ce0 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74  ferent VFSes wit
36cf0 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61  h the.** same na
36d00 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65  me are registere
36d10 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  d, the behavior 
36d20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49  is undefined.  I
36d30 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  f a.** VFS is re
36d40 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20  gistered with a 
36d50 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c  name that is NUL
36d60 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
36d70 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ring,.** then th
36d80 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
36d90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
36da0 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
36db0 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
36dc0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
36dd0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
36de0 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75 6c   ^(If the defaul
36df0 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
36e00 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
36e10 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
36e20 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
36e30 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
36e40 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
36e50 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73  rbitrary.)^.*/.s
36e60 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
36e70 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
36e80 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
36e90 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
36ea0 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
36eb0 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
36ec0 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
36ed0 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
36ee0 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
36ef0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f00 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a  REF: Mutexes.**.
36f10 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
36f20 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  re uses these ro
36f30 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61  utines for threa
36f40 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61  d.** synchroniza
36f50 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65  tion. Though the
36f60 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
36f70 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
36f80 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
36f90 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
36fa0 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
36fb0 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
36fc0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
36fd0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
36fe0 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
36ff0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
37000 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
37010 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20  entations.** of 
37020 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74  these mutex rout
37030 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70  ines.  An approp
37040 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61  riate implementa
37050 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63  tion.** is selec
37060 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ted automaticall
37070 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  y at compile-tim
37080 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  e.  ^(The follow
37090 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
370a0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
370b0 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
370c0 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
370d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
370e0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
370f0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
37100 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
37110 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
37120 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
37130 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
37140 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NOOP.** </ul>)^.
37150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  **.** ^The SQLIT
37160 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70  E_MUTEX_NOOP imp
37170 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
37180 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73   set of routines
37190 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
371a0 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e   real locking an
371b0 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  d is appropriate
371c0 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61   for use in.** a
371d0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
371e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e   application.  ^
371f0 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
37200 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f  _OS2,.** SQLITE_
37210 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61  MUTEX_PTHREAD, a
37220 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
37230 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  W32 implementati
37240 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f  ons.** are appro
37250 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f  priate for use o
37260 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e  n OS/2, Unix, an
37270 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a  d Windows..**.**
37280 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73 20   ^(If SQLite is 
37290 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
372a0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  e SQLITE_MUTEX_A
372b0 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73  PPDEF preprocess
372c0 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69  or.** macro defi
372d0 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c  ned (with "-DSQL
372e0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
372f0 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75  =1"), then no mu
37300 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
37310 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65  ation is include
37320 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
37330 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  ry. In this case
37340 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
37350 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
37360 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69  a custom mutex i
37370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
37380 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
37390 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
373a0 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73   option of the s
373b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
373c0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f  function.** befo
373d0 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  re calling sqlit
373e0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
373f0 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62  or any other pub
37400 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20  lic sqlite3_.** 
37410 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
37420 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
37430 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a  ialize().)^.**.*
37440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
37450 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
37460 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
37470 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
37480 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
37490 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 69  ter to it. ^If i
374a0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a  t returns NULL.*
374b0 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61  * that means tha
374c0 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20  t a mutex could 
374d0 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  not be allocated
374e0 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69  .  ^SQLite.** wi
374f0 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
37500 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
37510 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 20  n error.  ^(The 
37520 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
37530 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37540 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
37550 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
37560 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
37570 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
37580 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
37590 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
375a0 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
375b0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
375c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
375d0 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
375e0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
375f0 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
37600 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37610 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
37620 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37630 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
37640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
37650 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
37660 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
37670 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
37680 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
37690 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
376a0 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45  nts (SQLITE_MUTE
376b0 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
376c0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
376d0 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c 69  E).** cause sqli
376e0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
376f0 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61  ) to create.** a
37700 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 68   new mutex.  ^Th
37710 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72  e new mutex is r
37720 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51  ecursive when SQ
37730 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
37740 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20  SIVE.** is used 
37750 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  but not necessar
37760 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49  ily so when SQLI
37770 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73  TE_MUTEX_FAST is
37780 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75   used..** The mu
37790 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
377a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
377b0 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
377c0 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
377d0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
377e0 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c  ECURSIVE and SQL
377f0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
37800 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
37810 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69   want to.  ^SQLi
37820 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71  te will only req
37830 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65  uest a recursive
37840 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73   mutex in.** cas
37850 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c  es where it real
37860 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e  ly needs one.  ^
37870 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d  If a faster non-
37880 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a  recursive mutex.
37890 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
378a0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  n is available o
378b0 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66  n the host platf
378c0 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73  orm, the mutex s
378d0 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68  ubsystem.** migh
378e0 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20  t return such a 
378f0 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73  mutex in respons
37900 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  e to SQLITE_MUTE
37910 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54  X_FAST..**.** ^T
37920 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
37930 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
37940 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37950 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20 6f  oc() (anything o
37960 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c  ther.** than SQL
37970 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
37980 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
37990 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68 20  RECURSIVE) each 
379a0 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
379b0 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
379c0 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
379d0 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63 20  x.  ^Six static 
379e0 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
379f0 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
37a00 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
37a10 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
37a20 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
37a30 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
37a40 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
37a50 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
37a60 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
37a70 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
37a80 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
37a90 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37aa0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
37ab0 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
37ac0 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
37ad0 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
37ae0 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
37af0 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
37b00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
37b10 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  URSIVE..**.** ^N
37b20 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20  ote that if one 
37b30 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  of the dynamic m
37b40 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20  utex parameters 
37b50 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
37b60 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f  ST.** or SQLITE_
37b70 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
37b80 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71   is used then sq
37b90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37ba0 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  c().** returns a
37bb0 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78   different mutex
37bc0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20   on every call. 
37bd0 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73 74   ^But for the st
37be0 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79  atic.** mutex ty
37bf0 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
37c00 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
37c10 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
37c20 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
37c30 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a  me type number..
37c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37c50 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20  e3_mutex_free() 
37c60 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61  routine dealloca
37c70 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79  tes a previously
37c80 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79  .** allocated dy
37c90 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e 53  namic mutex.  ^S
37ca0 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
37cb0 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
37cc0 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
37cd0 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
37ce0 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64 79  locates.  The dy
37cf0 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
37d00 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20  st not be in.** 
37d10 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72  use when they ar
37d20 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20  e deallocated.  
37d30 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
37d40 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
37d50 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
37d60 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
37d70 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69  behavior.  ^SQLi
37d80 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
37d90 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
37da0 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54   mutex..**.** ^T
37db0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
37dc0 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c  _enter() and sql
37dd0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
37de0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
37df0 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20  t.** to enter a 
37e00 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74  mutex.  ^If anot
37e10 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c  her thread is al
37e20 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65  ready within the
37e30 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74   mutex,.** sqlit
37e40 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37e50 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20   will block and 
37e60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37e70 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  y() will return.
37e80 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ** SQLITE_BUSY. 
37e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
37ea0 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
37eb0 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
37ec0 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
37ed0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
37ee0 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72 65  .  ^(Mutexes cre
37ef0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ated using.** SQ
37f00 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
37f10 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65  SIVE can be ente
37f20 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
37f30 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
37f40 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63  hread..** In suc
37f50 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
37f60 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
37f70 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
37f80 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
37f90 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
37fa0 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
37fb0 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73 61  .)^  ^(If the sa
37fc0 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20  me thread tries 
37fd0 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68  to enter any oth
37fe0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75  er.** kind of mu
37ff0 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  tex more than on
38000 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ce, the behavior
38010 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
38020 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
38030 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73  ver exhibit.** s
38040 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20  uch behavior in 
38050 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d  its own use of m
38060 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  utexes.)^.**.** 
38070 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28  ^(Some systems (
38080 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e  for example, Win
38090 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20  dows 95) do not 
380a0 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72  support the oper
380b0 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ation.** impleme
380c0 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  nted by sqlite3_
380d0 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e  mutex_try().  On
380e0 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20   those systems, 
380f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
38100 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  y().** will alwa
38110 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ys return SQLITE
38120 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69  _BUSY.  The SQLi
38130 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65  te core only eve
38140 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65  r uses.** sqlite
38150 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73  3_mutex_try() as
38160 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
38170 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65   so this is acce
38180 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ptable behavior.
38190 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
381a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
381b0 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  e() routine exit
381c0 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
381d0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
381e0 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
381f0 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20 5e  same thread.   ^
38200 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a  (The behavior.**
38210 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
38220 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
38230 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
38240 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
38250 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
38260 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
38270 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
38280 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
38290 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a  r do either.)^.*
382a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
382b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
382c0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20  _mutex_enter(), 
382d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
382e0 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  y(), or.** sqlit
382f0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
38300 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38310 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72  er, then all thr
38320 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62  ee routines.** b
38330 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e  ehave as no-ops.
38340 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
38350 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
38360 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  held()] and [sql
38370 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
38380 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ld()]..*/.sqlite
38390 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33  3_mutex *sqlite3
383a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74  _mutex_alloc(int
383b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
383c0 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74  mutex_free(sqlit
383d0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64  e3_mutex*);.void
383e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
383f0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74  nter(sqlite3_mut
38400 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
38410 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69  3_mutex_try(sqli
38420 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
38430 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
38440 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75  leave(sqlite3_mu
38450 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
38460 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65  PI3REF: Mutex Me
38470 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
38480 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
38490 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
384a0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77   defines the low
384b0 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a  -level routines.
384c0 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63  ** used to alloc
384d0 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65  ate and use mute
384e0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c  xes..**.** Usual
384f0 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ly, the default 
38500 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
38510 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62  tions provided b
38520 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20  y SQLite are.** 
38530 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65  sufficient, howe
38540 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73  ver the user has
38550 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73   the option of s
38560 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75  ubstituting a cu
38570 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  stom.** implemen
38580 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69  tation for speci
38590 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e  alized deploymen
385a0 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f  ts or systems fo
385b0 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a  r which SQLite.*
385c0 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  * does not provi
385d0 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  de a suitable im
385e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e  plementation. In
385f0 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
38600 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20  user.** creates 
38610 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  and populates an
38620 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
38630 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70  s structure to p
38640 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ass.** to sqlite
38650 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67  3_config() along
38660 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
38670 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
38680 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74  option..** Addit
38690 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74  ionally, an inst
386a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
386b0 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  ucture can be us
386c0 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70  ed as an.** outp
386d0 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e  ut variable when
386e0 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79   querying the sy
386f0 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72  stem for the cur
38700 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  rent mutex.** im
38710 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73  plementation, us
38720 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
38730 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
38740 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   option..**.** ^
38750 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  The xMutexInit m
38760 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79  ethod defined by
38770 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
38780 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a  is invoked as.**
38790 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20   part of system 
387a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62  initialization b
387b0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
387c0 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  itialize() funct
387d0 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ion..** ^The xMu
387e0 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
387f0 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51 4c 69  is calle by SQLi
38800 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  te exactly once 
38810 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65  for each.** effe
38820 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73  ctive call to [s
38830 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
38840 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
38850 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f   xMutexEnd metho
38860 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
38870 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
38880 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
38890 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74  t of syste