/ Hex Artifact Content
Login

Artifact a7e17db2a3ab33d5f0f954b5fbc6a6c5dbef3581:


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 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1180: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1190: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
11a0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
11b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
11c0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
11d0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
11e0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
11f0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
1200: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
1210: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
1220: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
1230: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
1240: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1250: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1260: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1270: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1280: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1290: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12a0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
12b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
12c0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
12d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
12e0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
12f0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
1300: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
1310: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
1320: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
1330: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1340: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1350: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1360: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1370: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1380: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1390: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
13a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
13b0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
13c0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
13d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
1400: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
1410: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
1420: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1430: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1450: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1460: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1470: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1480: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1490: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
14a0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
14b0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
14c0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
14d0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
14f0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
1500: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
1510: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
1520: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1530: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
1540: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1550: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 20 70 6f  () function a po
1560: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74  inter.** to a st
1570: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1580: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1590: 20 73 61 6d 65 20 61 73 20 74 68 65 20 5b 53 51   same as the [SQ
15a0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 0a  LITE_SOURCE_ID].
15b0: 2a 2a 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ** C preprocesso
15c0: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
15d0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
15e0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
15f0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1600: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1610: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1620: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1630: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1640: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1650: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74  ion(void);.const
1660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1670: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69  ourceid(void);.i
1680: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
1690: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
16a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
16b0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
16c0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
16d0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
16e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1700: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1710: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1720: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1730: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1740: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1750: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1760: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1770: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1780: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1790: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
17a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
17b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
17c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
17d0: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
17e0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
17f0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1800: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1810: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1820: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1830: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1840: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1850: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1860: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1870: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1880: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1890: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
18a0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
18b0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
18c0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
18d0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
18e0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
18f0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1900: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1910: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1920: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1930: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1940: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1950: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1960: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1970: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1980: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1990: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
19a0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
19b0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
19c0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
19d0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
19e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
19f0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1a10: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1a20: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1a30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1a40: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1a50: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1a60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1a70: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1a80: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1a90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1aa0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1ab0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1ac0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1ad0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1ae0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1af0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1b00: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1b10: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1b20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1b30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1b40: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1b50: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1b60: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1b70: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1b80: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1b90: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1ba0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1bb0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1bc0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
1bd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1be0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1bf0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c00: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1c20: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
1c30: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
1c40: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1c50: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
1c60: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
1c70: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
1c80: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
1c90: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
1ca0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
1cb0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
1cc0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
1cd0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
1ce0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1cf0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1d00: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
1d10: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
1d20: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
1d30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
1d40: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
1d50: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
1d60: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
1d70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
1d80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1d90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1da0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1db0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dc0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1dd0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2070: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2080: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2090: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
20a0: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
20b0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
20c0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
20d0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
20e0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
20f0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
2100: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
2110: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2120: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2130: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2140: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2150: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2160: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2170: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2180: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2190: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
21a0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
21b0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
21c0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
21d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
21f0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
2200: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2210: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
2220: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2230: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2240: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2250: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2260: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2270: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2280: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2290: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
22a0: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
22b0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
22c0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
22d0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
22e0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
22f0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2320: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2330: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2340: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2350: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2360: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2370: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2380: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2390: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
23a0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
23b0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
23c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
23d0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
23e0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
23f0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2400: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2410: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2420: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2430: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2440: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2450: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2460: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2470: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2480: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2490: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
24a0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
24b0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
24c0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
24d0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
24e0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
24f0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2500: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2510: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2520: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2530: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2540: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2550: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2560: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2580: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2590: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
25a0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
25b0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
25c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
25d0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
25e0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
25f0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2600: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64   successfullly d
2610: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2620: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2630: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2640: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2650: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2660: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2670: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2680: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2690: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
26a0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
26b0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
26c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
26d0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
26e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
26f0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2700: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2710: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2720: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2730: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2740: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2760: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2770: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2780: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2790: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
27a0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
27b0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
27c0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
27d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
27e0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
27f0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2800: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2810: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2820: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2830: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2840: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2850: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2860: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2870: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2880: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2890: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28a0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
28c0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
28d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
28e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
28f0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2900: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2910: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2920: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2930: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2950: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2960: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68  terface.**.** Th
2a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2aa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2ab0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
2ac0: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
2ad0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ae0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2af0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2b00: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b10: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
2b20: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b30: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
2b40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
2b50: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
2b60: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
2b70: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
2b80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b90: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ba0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
2bb0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
2bc0: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
2bd0: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
2be0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
2bf0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
2c00: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
2c10: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
2c20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c30: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
2c40: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
2c50: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
2c60: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c70: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
2c80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
2c90: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
2ca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
2cb0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
2cc0: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
2cd0: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
2ce0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
2cf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
2d00: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
2d10: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  to.** to sqlite3
2d20: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
2d30: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
2d40: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
2d50: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
2d60: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
2d70: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
2d80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
2d90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
2da0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
2db0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
2dc0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
2dd0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
2de0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
2df0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2e00: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
2e10: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
2e20: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
2e30: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
2e40: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
2e50: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
2e60: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
2e70: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
2e80: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
2e90: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
2ea0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
2eb0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
2ec0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
2ed0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
2ee0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
2ef0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
2f00: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
2f10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f20: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
2f30: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
2f40: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2f50: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
2f60: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
2f70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2f80: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
2f90: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
2fa0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2fb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2fc0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2fd0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
2fe0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
2ff0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3000: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3010: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3020: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3030: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3040: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3050: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3060: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3070: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3080: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3090: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
30a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
30b0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
30c0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
30d0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
30e0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
30f0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3100: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3110: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3120: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3130: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3140: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3150: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3160: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3170: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3180: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3190: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
31a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
31b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
31c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
31d0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
31e0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31f0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3200: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3220: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3230: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3240: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3250: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3260: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3270: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3280: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3290: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
32a0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
32b0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
32c0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
32d0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
32e0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
32f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3300: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3320: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3330: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3340: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3350: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3370: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3380: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3390: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
33a0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
33b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
33c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
33d0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
33e0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
33f0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3400: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3410: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3420: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3430: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3440: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3450: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3460: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3470: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3480: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3490: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
34a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
34b0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
34c0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
34d0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
34e0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
34f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3500: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3510: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3520: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3530: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3540: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3550: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3560: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3570: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3590: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
35a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
35c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
35d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
35e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
35f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3600: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3610: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3630: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3640: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3650: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3660: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3670: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3680: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3690: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
36a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
36b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
36d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3700: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3710: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3730: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3740: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3750: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3760: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3770: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3780: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3790: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
37a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
37d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
37f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3810: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3820: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3840: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3850: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3860: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3870: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3880: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3890: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
38a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
38b0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
38c0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
38d0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
38e0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
38f0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3900: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3910: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3920: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3930: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3940: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3950: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3960: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3970: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3980: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3990: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
39a0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
39b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
39c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
39d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
39e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
39f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3a10: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3a20: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3a30: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a50: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3a60: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3a70: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3a80: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3a90: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3aa0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3ab0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3ac0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3ad0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3ae0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3af0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3b00: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b20: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3b30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3b40: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
3b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b60: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
3b70: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
3b80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
3b90: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
3ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
3bb0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
3bc0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
3bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3be0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
3bf0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
3c00: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
3c10: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
3c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3c30: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
3c40: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
3c50: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
3c60: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3c80: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
3c90: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
3ca0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
3cb0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
3cd0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
3ce0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
3cf0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
3d00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3d10: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
3d20: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
3d30: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
3d40: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
3d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
3d60: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
3d70: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
3d80: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
3d90: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
3da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
3db0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
3dc0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
3dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
3de0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3df0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
3e00: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
3e10: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
3e20: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
3e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e40: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
3e50: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
3e60: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
3e70: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
3e80: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
3e90: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
3ea0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
3ec0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
3ed0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
3ee0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
3ef0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
3f10: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
3f20: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
3f30: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
3f50: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
3f60: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
3f70: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
3f80: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
3f90: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
3fa0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
3fb0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
3fc0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
3fd0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
3fe0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
3ff0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4010: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
4020: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
4030: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4050: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4060: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4070: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4090: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
40a0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
40b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
40c0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
40d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40e0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
40f0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4100: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
4110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4130: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4140: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4150: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4160: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4180: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4190: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
41a0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
41b0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
41c0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
41d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
41e0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
41f0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4200: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
4220: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
4230: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4240: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4250: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4260: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4270: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4280: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4290: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
42a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
42b0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
42c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
42e0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
42f0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4300: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
4310: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
4320: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
4330: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4340: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4350: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4360: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4370: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4380: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4390: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
43a0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
43b0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
43c0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
43d0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
43e0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
43f0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4400: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
4410: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
4420: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
4430: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4440: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4450: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4460: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4470: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4480: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
44a0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
44b0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
44c0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
44d0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
44e0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
44f0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4500: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4510: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4520: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4530: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4550: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4560: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4570: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4580: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4590: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
45a0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
45b0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
45c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
45d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
45e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
45f0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4600: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4610: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4620: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4630: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4650: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4670: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4690: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
46a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
46b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
46d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
46f0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4710: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4730: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4750: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4760: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4770: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4780: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4790: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
47a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
47b0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
47c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
47d0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
47e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
47f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4800: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4810: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4840: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4850: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4860: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4880: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
48b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
48c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
48d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
48f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4900: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4920: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4940: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4950: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4960: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4980: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4990: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
49a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
49b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
49c0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
49d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
49f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a00: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4a10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4a30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a40: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4a50: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4a60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a80: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4a90: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4aa0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4ab0: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4ac0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4ad0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4ae0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
4af0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4b00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4b20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4b30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4b40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
4b50: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
4b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4b70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
4b80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4b90: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
4bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
4bd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c00: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
4c10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
4c20: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c50: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
4c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4c70: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ca0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
4cb0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
4cc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
4cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
4d00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
4d30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
4d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
4d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
4d80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4da0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
4db0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
4dc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4de0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
4df0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
4e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
4e30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
4e40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
4e70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
4e80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ea0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
4eb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
4ec0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ee0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
4ef0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
4f00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4f10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
4f40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
4f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
4f90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
4fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
4fe0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
4ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5020: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5030: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5040: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5050: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5060: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5070: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
5080: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
5090: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
50a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
50b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
50c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
50d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
50e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
50f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5100: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5110: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5120: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5130: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5140: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5150: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5160: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5170: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5180: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5190: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
51a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
51c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
51d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
51e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
51f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5200: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5210: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5220: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5230: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5240: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5250: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5260: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5270: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5280: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5290: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
52a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
52c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
52d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
52e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
52f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5310: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5320: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5330: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5340: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5350: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5360: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5370: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
53a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
53d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5430: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5550: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5570: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5580: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
55a0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
55b0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
55c0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
55d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
55e0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
55f0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
5600: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
5610: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
5620: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
5630: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
5640: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5650: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5670: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
5680: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5690: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
56a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
56b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
56c0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
56e0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5700: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
5710: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
5720: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
5730: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
5740: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5750: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5760: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5770: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5790: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
57a0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
57b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
57c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
57d0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
57e0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
57f0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5800: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5810: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5820: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5830: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5840: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5850: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5860: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5870: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5880: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5890: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
58a0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
58b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
58c0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
58d0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
58e0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
58f0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5900: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5910: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5920: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
5930: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
5940: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5950: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5960: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5970: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
59a0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
59b0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
59c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
59d0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
59e0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
59f0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5a00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5a10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
5a20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5a30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
5a40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
5a50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
5a60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
5a70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
5a80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5a90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
5aa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5ab0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5ac0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5ad0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5ae0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5af0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
5b00: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
5b10: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
5b20: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
5b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5b40: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
5b50: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
5b60: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
5b70: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
5b80: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
5b90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5ba0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
5bb0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
5bc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
5bd0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
5be0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5bf0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
5c00: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
5c10: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
5c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5c30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
5c40: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
5c50: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
5c60: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
5c70: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
5c80: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
5c90: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
5ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
5cb0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
5cc0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
5cd0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
5ce0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5cf0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
5d00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
5d10: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
5d20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
5d30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
5d40: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
5d50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5d60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
5d70: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
5d80: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
5d90: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
5da0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
5db0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f  .**.** If the xO
5dc0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20  pen method sets 
5dd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
5de0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
5df0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
5e00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
5e10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
5e20: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
5e30: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
5e40: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
5e50: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72   the xOpen repor
5e60: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
5e70: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
5e80: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
5e90: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
5ea0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
5eb0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20  led xOpen.** is 
5ec0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f  for the xOpen to
5ed0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
5ee0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
5ef0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a  lement to NULL..
5f00: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5f10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5f20: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5f30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
5f40: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
5f50: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
5f60: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
5f70: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
5f80: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
5f90: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
5fa0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
5fb0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
5fc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
5fd0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
5fe0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
5ff0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6000: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6010: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
6020: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
6030: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
6040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
6060: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6070: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6080: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6090: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
60a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
60b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
60c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
60e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6100: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6110: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6120: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6130: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6140: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6150: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
6160: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
6170: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6180: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6190: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
61a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
61b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
61c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
61d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
61e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
61f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6200: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6210: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6220: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6230: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6240: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6250: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
6260: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
6270: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6280: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6290: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
62a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
62b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
62c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
62d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
62e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
62f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6310: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6320: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6330: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6340: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6350: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
6360: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
6370: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6380: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6390: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
63a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
63b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
63c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
63d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
63e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
63f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6400: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6410: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6420: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6430: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6440: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6450: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
6460: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
6470: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6480: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6490: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
64a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
64b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
64c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
64d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
64e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
64f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6500: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6510: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6520: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6530: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6540: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6550: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6560: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
6570: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6580: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6590: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
65a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
65b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
65c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
65d0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
65e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
65f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6600: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6610: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6620: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6630: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6640: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6650: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
6660: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
6670: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6680: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6690: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
66a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
66b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
66c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
66d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
66e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
66f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6700: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6710: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
6720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6740: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6750: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
6760: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6770: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6780: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6790: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
67a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
67c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6810: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6840: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6860: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
6870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6880: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
68a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
68b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
68c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
68d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
68e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
68f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6900: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6910: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6920: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6930: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6940: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6950: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6960: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6970: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6980: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6990: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
69a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
69b0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
69c0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
69d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
69e0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
69f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6a10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6a20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6a30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6a40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6a50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6a60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6a70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6a80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6a90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6aa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6ab0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6ac0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
6ad0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
6ae0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
6af0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
6b00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
6b10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
6b20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
6b30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
6b40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
6b50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
6b60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
6b70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
6b80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
6b90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
6ba0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
6bb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
6bc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
6bd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
6be0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
6bf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6c00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
6c10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
6c20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6c30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
6c40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
6c50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
6c60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6c70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6c80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6c90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6ca0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6cb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6cd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6ce0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6cf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
6d00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
6d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
6d20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
6d30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
6d40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6d50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
6d60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
6d70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6d80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6d90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6da0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6db0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6dc0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6dd0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6de0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6df0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6e00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
6e10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
6e20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
6e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6e40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
6e50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
6e60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
6e70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6e80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6e90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
6ea0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
6eb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
6ec0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
6ed0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
6ee0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6ef0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
6f00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
6f10: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
6f20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6f30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6f40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6f50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6f60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6f70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6f80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
6f90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6fa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6fb0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
6fc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6fd0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
6fe0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
6ff0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7000: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7010: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7020: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7030: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7040: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7050: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7060: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7070: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7080: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7090: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
70a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
70b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
70c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
70d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
70e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
70f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7100: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7110: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7120: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7130: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7140: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
7150: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
7160: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
7170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7180: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7190: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
71a0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
71b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
71c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
71d0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
71e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
71f0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7200: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
7210: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7220: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
7230: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7240: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7250: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
7260: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
7270: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
7280: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
7290: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
72a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
72b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
72c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
72d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
72e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
72f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7300: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7310: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7320: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7330: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7340: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7350: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
7360: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
7370: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7380: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
7390: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
73a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
73b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
73c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
73d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
73e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
73f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
7400: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
7410: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
7420: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
7430: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
7440: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
7450: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
7460: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
7470: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7480: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
7490: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
74a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
74b0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
74c0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
74d0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
74e0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
74f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7500: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
7510: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
7520: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
7530: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
7540: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
7550: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
7560: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
7570: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
7580: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
7590: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
75a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
75b0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
75c0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
75d0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
75e0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
75f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
7600: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
7610: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7620: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
7630: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
7640: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
7650: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
7660: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
7670: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
7680: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
7690: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
76a0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
76b0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
76c0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
76d0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
76e0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
76f0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
7700: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
7710: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
7720: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
7730: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
7740: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
7750: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
7760: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
7770: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
7780: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
7790: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
77a0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
77b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
77c0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
77d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
77e0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
77f0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7810: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7820: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7830: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
7840: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7850: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
7860: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
7870: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
7880: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
7890: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
78a0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
78b0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
78c0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
78d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
78e0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
78f0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7900: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7910: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7920: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7930: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7940: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7950: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
7960: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
7970: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
7980: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
7990: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
79a0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
79b0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
79c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
79d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
79e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
79f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
7a00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
7a10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
7a20: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
7a30: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
7a40: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
7a50: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
7a60: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
7a70: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
7a80: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
7a90: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
7aa0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
7ab0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
7ac0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
7ad0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
7ae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
7af0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
7b00: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
7b10: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
7b20: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7b30: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
7b40: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7b50: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
7b60: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
7b70: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
7b80: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
7b90: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
7ba0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
7bb0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
7bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7bd0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
7be0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
7bf0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
7c00: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
7c10: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
7c20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
7c30: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
7c40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7c50: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
7c60: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
7c70: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
7c80: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
7c90: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
7ca0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
7cb0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
7cc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
7cd0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
7ce0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7cf0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7d00: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7d10: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7d20: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
7d30: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
7d40: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7d50: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
7d60: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
7d70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
7d80: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
7d90: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
7da0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
7db0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
7dc0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
7dd0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7de0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7df0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7e00: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7e10: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7e20: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
7e30: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
7e40: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
7e50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7e60: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
7e70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7e80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
7e90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
7ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7eb0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7ec0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7ed0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
7ee0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7ef0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
7f00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7f10: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
7f20: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
7f30: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7f40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7f50: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
7f60: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
7f70: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
7f80: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
7f90: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
7fa0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
7fb0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
7fc0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
7fd0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
7fe0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
7ff0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8000: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8010: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8020: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8030: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8040: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8050: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8060: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8070: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8080: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8090: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
80a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
80b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
80c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
80d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
80e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
80f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8100: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8110: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8120: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8130: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8140: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8150: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8160: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8170: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8180: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
81b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
81c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
81d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
81e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
81f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8200: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8210: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8220: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8230: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8240: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
8250: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8260: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8270: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8280: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8290: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
82a0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
82b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
82c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
82d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
82e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
82f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8310: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
8320: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
8330: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
8340: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
8350: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
8360: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
8370: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
8380: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8390: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
83a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
83b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
83c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
83d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
83e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
83f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
8400: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
8410: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
8420: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
8430: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
8440: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
8450: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
8460: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
8470: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
8480: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74  access..**.** At
8490: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
84a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
84b0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
84c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
84d0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
84e0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
84f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8500: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8510: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8520: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8530: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8540: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8550: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8560: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8570: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
8580: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
8590: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
85a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
85b0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
85c0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
85d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
85e0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
85f0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
8600: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
8610: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
8620: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
8630: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
8640: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
8650: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
8660: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
8670: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
8680: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
8690: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
86a0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
86b0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54  en call..**.** T
86c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
86d0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
86e0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
86f0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8700: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8710: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8720: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8730: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8740: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
8750: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
8760: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
8770: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
8780: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8790: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
87a0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
87b0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
87c0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
87d0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
87e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
87f0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8800: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8810: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8820: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8830: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8840: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
8850: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
8860: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8870: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
8880: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
8890: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
88a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
88b0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
88c0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
88d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
88e0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
88f0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8900: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8910: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8920: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8930: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8940: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8950: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
8960: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
8970: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8980: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
89a0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
89b0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
89c0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
89d0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
89e0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
89f0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
8a00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
8a10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
8a20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
8a30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
8a40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8a50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
8a60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
8a70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
8a80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
8a90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
8aa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
8ab0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
8ac0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
8ad0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
8ae0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
8af0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
8b00: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
8b10: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
8b20: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
8b30: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
8b40: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
8b50: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
8b60: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
8b70: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8b80: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
8b90: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
8ba0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
8bb0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79  d time..**.*/.ty
8bc0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8bd0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
8be0: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
8bf0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
8c00: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
8c10: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
8c20: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
8c30: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
8c40: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
8c50: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
8c60: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
8c70: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
8c80: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
8c90: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
8ca0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
8cb0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
8cc0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
8cd0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
8ce0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
8cf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
8d00: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
8d10: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
8d20: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
8d30: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
8d40: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
8d50: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
8d60: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
8d70: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
8d80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8d90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8da0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
8db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
8dc0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
8dd0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
8de0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
8df0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e00: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e10: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
8e20: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
8e30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e50: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
8e60: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e70: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
8e80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8e90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
8ea0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
8eb0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
8ec0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
8ed0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8ee0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
8ef0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
8f00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8f10: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
8f20: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
8f30: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
8f40: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
8f50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
8f60: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
8f70: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
8f80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8f90: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
8fa0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
8fb0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
8fc0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
8fd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
8fe0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
8ff0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9000: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9010: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9020: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9030: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9040: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9050: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9060: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69   *);.  /* New fi
9070: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9080: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
9090: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
90a0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
90b0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
90c0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
90d0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
90e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
90f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9100: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9110: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9120: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9130: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9140: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9150: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
9160: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
9170: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9180: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
9190: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
91a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
91b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
91c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
91d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
91e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
91f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9200: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9210: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9220: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9230: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9240: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9250: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9260: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9270: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9280: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9290: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
92a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
92b0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
92c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
92d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
92e0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
92f0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9300: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9310: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9320: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9330: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9340: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9350: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
9360: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
9370: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
9380: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
9390: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
93a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
93b0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
93c0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
93d0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
93e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
93f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9400: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9410: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9420: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9440: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9450: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
9460: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
9470: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
9480: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
9490: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
94a0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
94b0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
94c0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
94d0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
94e0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
94f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9500: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9510: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9520: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9530: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9540: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9550: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9560: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9570: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9580: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9590: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
95a0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
95b0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
95c0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
95d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
95e0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
95f0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9600: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9610: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
9620: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9630: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9640: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9650: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
9660: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9670: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9680: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
9690: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
96a0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
96b0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
96c0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
96d0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
96e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
96f0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
9700: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
9710: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
9720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
9730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
9750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
9760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
9770: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
9780: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9790: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
97a0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
97b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
97c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
97d0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
97e0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
97f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
9800: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
9810: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
9820: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
9830: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
9840: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
9850: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
9860: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9870: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
9880: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
9890: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
98a0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
98b0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
98c0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
98d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
98e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
98f0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
9900: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9910: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9920: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9930: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9940: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
9950: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
9960: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
9970: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
9980: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9990: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
99a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
99b0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
99c0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
99d0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
99e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
99f0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
9a00: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
9a10: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
9a20: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9a30: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
9a40: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
9a50: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
9a60: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
9a70: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
9a80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
9a90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
9aa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9ab0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9ac0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9ad0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ae0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9af0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9b00: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9b10: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9b20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9b30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9b40: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9b50: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9b60: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9b70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9b80: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9b90: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9ba0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9bb0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9bc0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9bd0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9be0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9bf0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9c00: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
9c10: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
9c20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
9c30: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
9c40: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
9c50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
9c60: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
9c70: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
9c80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9c90: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
9ca0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
9cb0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
9cc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9cd0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
9ce0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
9cf0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
9d00: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
9d10: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
9d20: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
9d30: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
9d40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
9d50: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
9d60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
9d70: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
9d80: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
9d90: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
9da0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
9db0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
9dc0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
9dd0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
9de0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
9df0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
9e00: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
9e10: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
9e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9e30: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
9e40: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
9e50: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
9e60: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
9e70: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
9e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
9e90: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
9ea0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
9eb0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
9ec0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
9ed0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
9ee0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
9ef0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
9f00: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
9f10: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
9f20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
9f30: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
9f40: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
9f50: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
9f60: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
9f70: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
9f80: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
9f90: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
9fa0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
9fb0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
9fc0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
9fd0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
9fe0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
9ff0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
a000: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a010: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
a020: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
a030: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
a040: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a050: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
a060: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a070: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
a080: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
a090: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
a0a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
a0b0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a0c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
a0d0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
a0e0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
a0f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
a100: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
a110: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
a120: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
a130: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
a140: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
a150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
a160: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a170: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
a180: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a190: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
a1a0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
a1b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a1c0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
a1d0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
a1e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
a1f0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
a200: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
a210: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
a220: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a230: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
a240: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
a250: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
a260: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a270: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a280: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a290: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a2a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a2b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a2c0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a2d0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a2e0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a2f0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a300: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a310: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a320: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a330: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
a340: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a350: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
a360: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
a370: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
a380: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
a3a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
a3b0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
a3c0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
a3d0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
a3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
a3f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
a400: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
a410: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a420: 61 72 79 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ary.** EXPERIMEN
a430: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
a440: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a450: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a460: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a470: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a480: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a490: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a4a0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a4b0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a4c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a4d0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a4e0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a4f0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a500: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a510: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a520: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a530: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a540: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a550: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a560: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a570: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a580: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a590: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a5a0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a5b0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a5c0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a5d0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a5e0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a5f0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a600: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a610: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a620: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a630: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a640: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a650: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a660: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a670: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a680: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a690: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a6a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a6c0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a6d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a6e0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
a6f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a700: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
a710: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
a720: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
a730: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
a740: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
a750: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
a760: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
a770: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a780: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
a790: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
a7a0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
a7b0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
a7c0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
a7d0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
a7e0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
a7f0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
a800: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
a810: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a820: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a840: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a860: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
a870: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
a880: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
a890: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
a8a0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
a8b0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
a8c0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
a8d0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
a8e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
a8f0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
a900: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
a910: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
a920: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
a930: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a940: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a950: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a960: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a970: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
a980: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
a990: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
a9a0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
a9b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
a9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
a9d0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
a9e0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
a9f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
aa00: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
aa10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
aa20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
aa30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
aa40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
aa50: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
aa60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
aa70: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
aa80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
aa90: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
aaa0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
aab0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
aac0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
aad0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
aae0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
aaf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ab00: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
ab10: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
ab20: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
ab30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ab40: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
ab50: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ab60: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
ab70: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ab80: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
ab90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
aba0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
abb0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
abc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
abd0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
abe0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
abf0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
ac00: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
ac10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
ac20: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
ac30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ac40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ac50: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
ac60: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
ac70: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
ac80: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
ac90: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
aca0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
acb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
acc0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
acd0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
ace0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
acf0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
ad00: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
ad10: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
ad20: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
ad30: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
ad40: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
ad50: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
ad60: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
ad70: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
ad80: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
ad90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
ada0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
adb0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
adc0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
add0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
ade0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
adf0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
ae00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
ae10: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ae20: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
ae30: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
ae40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
ae50: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
ae60: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49  utines.** EXPERI
ae70: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
ae80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ae90: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
aea0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
aeb0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
aec0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
aed0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
aee0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
aef0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
af00: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
af10: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
af20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
af30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
af40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
af50: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
af60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
af70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
af80: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
af90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
afa0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
afb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
afc0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
afd0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
afe0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
aff0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
b010: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
b020: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b030: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b040: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
b050: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
b060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
b070: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
b080: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
b090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
b0a0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
b0b0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
b0c0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
b0d0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
b0e0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
b0f0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
b100: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
b110: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
b120: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
b130: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
b140: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
b150: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
b160: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
b170: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
b180: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
b190: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
b1a0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
b1b0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
b1c0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
b1d0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
b1e0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
b1f0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
b200: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
b210: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
b220: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
b230: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
b240: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b260: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
b270: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
b280: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
b290: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
b2a0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
b2b0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
b2c0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
b2d0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
b2e0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
b2f0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
b300: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
b310: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
b320: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
b330: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
b340: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
b350: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
b360: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
b370: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
b380: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
b390: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
b3a0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
b3b0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
b3c0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b3d0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
b3e0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
b3f0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
b400: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
b410: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
b420: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
b430: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
b440: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
b450: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
b470: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
b480: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
b490: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
b4a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
b4b0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
b4c0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
b4d0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
b4e0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
b4f0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
b500: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
b510: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
b520: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
b530: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
b540: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
b550: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
b560: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
b570: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
b580: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
b590: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
b5a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b5b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
b5c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
b5d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
b5e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
b5f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
b600: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
b610: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
b620: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
b630: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
b640: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
b650: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
b660: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
b670: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b680: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
b690: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b6a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b6b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b6c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b6d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b6e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b6f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b700: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b710: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b720: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b730: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b740: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b750: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
b760: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
b770: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
b780: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
b790: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
b7a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
b7b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
b7c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
b7d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
b7e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
b7f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
b800: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
b810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b820: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
b830: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
b840: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
b850: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b860: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
b870: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
b880: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
b890: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
b8a0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
b8b0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
b8c0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
b8d0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
b8e0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
b8f0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
b900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
b910: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
b920: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
b930: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
b940: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
b950: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
b960: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
b970: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
b980: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
b990: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
b9a0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
b9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
b9c0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
b9d0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
b9e0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
b9f0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
ba00: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
ba10: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
ba20: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
ba30: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
ba40: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
ba50: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ba60: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
ba70: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
ba80: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
ba90: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
baa0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
bab0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
bac0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
bad0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
bae0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
baf0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
bb00: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
bb10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bb20: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
bb30: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
bb40: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
bb50: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
bb60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
bb70: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
bb80: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
bb90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
bba0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
bbb0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
bbc0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
bbd0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
bbe0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
bbf0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
bc00: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
bc10: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
bc20: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
bc30: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
bc40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
bc50: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
bc60: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
bc70: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
bc80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bc90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bca0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
bcb0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
bcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bcd0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
bce0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
bcf0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
bd00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
bd10: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
bd20: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
bd30: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
bd40: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
bd50: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
bd60: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
bd70: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
bd80: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
bd90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
bda0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
bdb0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
bdc0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
bdd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
bde0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
bdf0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
be00: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
be10: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
be20: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
be30: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
be40: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
be50: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
be60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
be70: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
be80: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
be90: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
bea0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
beb0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
bec0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
bed0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
bee0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
bef0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
bf00: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
bf10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
bf30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
bf40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
bf50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
bf60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
bf70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bf80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
bf90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
bfa0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bfb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
bfc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
bfd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
bfe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
bff0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
c000: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
c010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
c020: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
c030: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c040: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
c050: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
c060: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
c070: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
c080: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
c090: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c0a0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
c0b0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
c0c0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
c0d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
c0e0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
c0f0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
c100: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
c110: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
c120: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
c130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c140: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
c150: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
c160: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c170: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
c180: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
c190: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
c1a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
c1b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
c1c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
c1d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
c1e0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
c1f0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
c200: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
c210: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
c220: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
c230: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
c240: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
c250: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
c260: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
c270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
c280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
c290: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
c2a0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
c2b0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
c2c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
c2d0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
c2e0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
c2f0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
c300: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
c310: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
c320: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
c330: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
c340: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
c350: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
c360: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
c370: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
c380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c390: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
c3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c3b0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
c3c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c3d0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
c3e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c3f0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c400: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c410: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
c420: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
c430: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
c440: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
c450: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
c460: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
c470: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c490: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c4a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
c4b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c4c0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
c4d0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
c4e0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
c4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c500: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
c510: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
c520: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
c530: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
c540: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
c550: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
c560: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
c570: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
c580: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
c590: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
c5a0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
c5b0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
c5c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c5d0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
c5e0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
c5f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
c600: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
c610: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
c620: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
c630: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
c640: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
c650: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
c660: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
c670: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
c680: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
c690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c6a0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
c6b0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
c6c0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
c6d0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
c6e0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
c6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c700: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
c710: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c720: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
c730: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c740: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c750: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c760: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
c770: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
c780: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
c790: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
c7a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
c7b0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
c7c0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
c7d0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
c7e0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
c7f0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
c800: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
c810: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
c820: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
c830: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
c840: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
c850: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
c860: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
c870: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
c880: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
c890: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
c8a0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
c8b0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
c8c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c8d0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
c8e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
c8f0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
c900: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
c910: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
c920: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
c930: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
c940: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
c960: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
c970: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
c980: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
c990: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c9a0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
c9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
c9c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
c9d0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
c9e0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
c9f0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
ca00: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
ca10: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
ca20: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
ca30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ca40: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
ca50: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
ca60: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
ca70: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
ca80: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
ca90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
caa0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
cab0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cac0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
cad0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
cae0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
caf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
cb00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
cb10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
cb20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
cb30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
cb40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
cb50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
cb60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
cb70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
cb80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
cb90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cba0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
cbb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cbc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
cbd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
cbe0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
cbf0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
cc00: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
cc10: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
cc20: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
cc30: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
cc40: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
cc50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
cc60: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
cc70: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cc80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
cc90: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
cca0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ccb0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ccc0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ccd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cce0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
ccf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
cd00: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cd10: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
cd20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
cd30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
cd40: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
cd50: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
cd60: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
cd70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
cd80: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
cd90: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
cda0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
cdb0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
cdc0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
cdd0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
cde0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
cdf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ce00: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
ce10: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
ce20: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
ce30: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
ce40: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ce50: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
ce60: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
ce70: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
ce80: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
ce90: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
cea0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
ceb0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
cec0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
ced0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
cee0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
cef0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
cf00: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
cf10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
cf20: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
cf30: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
cf40: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
cf50: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
cf60: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
cf70: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
cf80: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
cf90: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
cfa0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
cfb0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
cfc0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
cfd0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
cfe0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
cff0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
d000: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
d010: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
d020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
d030: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
d040: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
d050: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
d060: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
d070: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
d080: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
d090: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
d0a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
d0b0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d0c0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
d0d0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
d0e0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d0f0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
d100: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
d110: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
d120: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
d130: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
d140: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
d150: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
d160: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
d170: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
d180: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
d190: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
d1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
d1b0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63   which the scrac
d1c0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
d1d0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
d1e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
d1f0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
d200: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
d210: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
d220: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
d230: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
d240: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
d250: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
d260: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
d270: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
d280: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
d290: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
d2a0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
d2b0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
d2c0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74  uired due to int
d2d0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
d2e0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d2f0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
d310: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
d320: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
d330: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
d340: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
d350: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
d360: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
d370: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72  ratch buffer per
d380: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
d390: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
d3a0: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
d3b0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
d3c0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c  f threads.  ^SQL
d3d0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
d3e0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
d3f0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
d400: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74  is more than 6 t
d410: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
d420: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20  e.** page size. 
d430: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
d440: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
d450: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  l scratch memory
d460: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74   beyond .** what
d470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
d480: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
d490: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
d4a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
d4b0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
d4c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
d4d0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
d4e0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d4f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
d500: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
d510: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
d520: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
d530: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
d540: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
d550: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
d560: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
d570: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
d580: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
d590: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e  e implemenation.
d5a0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
d5b0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
d5c0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
d5d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
d5e0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
d5f0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d600: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
d610: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
d620: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
d630: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
d640: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
d650: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
d660: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
d670: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
d680: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
d690: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
d6a0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
d6b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
d6c0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
d6d0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d6e0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
d6f0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
d700: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
d710: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
d720: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
d730: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
d740: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
d750: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
d760: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
d770: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
d780: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
d790: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
d7a0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
d7b0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
d7c0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
d7d0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
d7e0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
d7f0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
d800: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
d810: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d820: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
d830: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
d840: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
d850: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
d860: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d870: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
d880: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
d890: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
d8a0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
d8b0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
d8c0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
d8d0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
d8e0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
d8f0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
d900: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
d910: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
d920: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
d930: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
d940: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
d960: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
d970: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
d980: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  space..** ^The i
d990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d9a0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
d9b0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
d9c0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
d9d0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
d9e0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
d9f0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
da00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
da10: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
da20: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
da30: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
da40: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
da50: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
da60: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
da80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
da90: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
daa0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
dab0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
dac0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
dad0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
dae0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
daf0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
db00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
db10: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
db20: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
db30: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
db40: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
db50: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
db60: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
db70: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
db80: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
db90: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
dba0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
dbb0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
dbc0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
dbd0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
dbe0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
dbf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
dc00: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
dc10: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
dc20: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
dc30: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
dc40: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
dc50: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
dc60: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
dc70: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
dc80: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
dc90: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
dca0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
dcb0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
dcc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
dcd0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
dce0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
dd00: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
dd10: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
dd20: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
dd30: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
dd40: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
dd50: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
dd60: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
dd70: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
dd80: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
dd90: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
dda0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
ddb0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
ddc0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
ddd0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
dde0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
ddf0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
de00: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
de10: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
de20: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
de30: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
de40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
de50: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
de60: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
de70: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
de80: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
de90: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
dea0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
deb0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
dec0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ded0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
dee0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
def0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
df00: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
df10: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
df20: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
df30: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
df40: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
df50: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
df60: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
df70: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
df80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
df90: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
dfa0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
dfb0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
dfc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
dfd0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
dfe0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
dff0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
e000: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
e010: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
e020: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
e030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e040: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
e050: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
e060: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
e070: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
e080: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
e090: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e0a0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
e0b0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e0c0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
e0d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
e0e0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
e0f0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
e100: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e110: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
e120: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e130: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e140: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e150: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e160: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e170: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e180: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
e190: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e1a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
e1b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e1c0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e1d0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e1e0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e1f0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
e200: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
e210: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
e220: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
e230: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
e240: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
e250: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
e260: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
e270: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
e280: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
e290: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
e2a0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
e2b0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
e2c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e2d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e2e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e2f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e300: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e310: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e320: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
e330: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
e340: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
e350: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
e360: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
e370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e380: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
e390: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
e3a0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
e3b0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
e3c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e3d0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
e3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e3f0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
e400: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
e410: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
e420: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
e430: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
e440: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
e450: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
e460: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
e470: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
e480: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
e490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
e4a0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
e4b0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
e4c0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
e4d0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
e4e0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
e4f0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e500: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
e510: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
e520: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e530: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
e540: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
e550: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
e560: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
e570: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
e580: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
e590: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
e5a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
e5b0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
e5c0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
e5d0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
e5e0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
e5f0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
e600: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
e610: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
e620: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
e630: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
e640: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
e650: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
e660: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
e670: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
e680: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
e690: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
e6a0: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
e6b0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
e6c0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
e6d0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
e6e0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
e6f0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
e700: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
e710: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
e720: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
e730: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
e740: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e750: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
e760: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
e770: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
e780: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
e790: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
e7a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
e7b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
e7c0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
e7d0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
e7e0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
e7f0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
e800: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e810: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
e820: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
e830: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
e840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
e850: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
e860: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
e870: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
e880: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
e890: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
e8a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e8b0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
e8c0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
e8d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
e8e0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
e8f0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
e900: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
e910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
e920: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
e930: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
e940: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
e960: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
e970: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
e980: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
e990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
e9b0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
e9c0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
e9d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e9e0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
e9f0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
ea00: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
ea10: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
ea20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ea30: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
ea40: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
ea50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ea60: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
ea70: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
ea80: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
ea90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
eaa0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
eab0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
eac0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
ead0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
eae0: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
eaf0: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
eb00: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
eb10: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
eb20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
eb30: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
eb40: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
eb50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
eb60: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
eb70: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
eb80: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
eb90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
eba0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
ebb0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
ebc0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
ebd0: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  hods* */../*.** 
ebe0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
ebf0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
ec00: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
ec10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
ec20: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
ec30: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
ec40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ec50: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
ec60: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
ec70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ec80: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
ec90: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
eca0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
ecb0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
ecc0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
ecd0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
ece0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
ecf0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
ed00: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
ed10: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
ed20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
ed30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
ed40: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
ed50: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
ed60: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
ed70: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
ed80: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
ed90: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
eda0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
edb0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
edc0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
edd0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ede0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
edf0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
ee00: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ee20: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
ee30: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
ee40: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
ee50: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
ee60: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
ee70: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
ee80: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
ee90: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
eea0: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
eeb0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
eec0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
eed0: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
eee0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eef0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
ef00: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
ef10: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
ef20: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
ef30: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
ef40: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
ef50: 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  an memory buffer
ef60: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
ef70: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
ef80: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
ef90: 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
efa0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
efb0: 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
efc0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
efd0: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
efe0: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
eff0: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
f000: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
f010: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
f020: 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
f030: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f040: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f050: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f060: 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
f070: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
f080: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
f090: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
f0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
f0b0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
f0c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
f0d0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
f0e0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
f0f0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
f100: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
f110: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
f120: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
f130: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
f140: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
f150: 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
f160: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
f170: 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
f180: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
f190: 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
f1a0: 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
f1b0: 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
f1c0: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
f1d0: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74   smaller.** mult
f1e0: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20  iple of 8.  See 
f1f0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f  also: [SQLITE_CO
f200: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c  NFIG_LOOKASIDE]<
f210: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
f220: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f230: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f240: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f  ASIDE    1001  /
f250: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
f260: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
f270: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
f280: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
f290: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
f2a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f2b0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
f2c0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
f2d0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
f2e0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
f2f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
f300: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
f310: 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
f320: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
f330: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
f340: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
f350: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
f360: 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
f370: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
f380: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
f390: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
f3a0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
f3b0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
f3c0: 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
f3d0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
f3e0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
f3f0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
f400: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
f410: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
f420: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
f430: 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
f440: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
f450: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
f460: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
f470: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
f480: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
f490: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
f4a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
f4b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
f4c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
f4d0: 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
f4e0: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
f4f0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
f500: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
f510: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
f520: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
f530: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
f540: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
f550: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
f560: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
f570: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
f580: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
f590: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
f5a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
f5b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
f5d0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f5e0: 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63  ent.  ^If no suc
f5f0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
f600: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
f610: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
f620: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f630: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
f640: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
f650: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
f660: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
f670: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
f680: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
f690: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
f6a0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
f6b0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
f6c0: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
f6d0: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
f6e0: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
f6f0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
f700: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
f710: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
f720: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
f730: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
f740: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
f750: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
f760: 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
f770: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
f780: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
f790: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
f7a0: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
f7b0: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
f7c0: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
f7d0: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
f7e0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
f7f0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
f800: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
f810: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
f820: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
f830: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
f840: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
f850: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
f860: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
f870: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
f880: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
f890: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
f8a0: 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
f8b0: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
f8c0: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
f8d0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
f8e0: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
f8f0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
f900: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
f910: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
f920: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
f930: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
f940: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
f950: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
f960: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
f970: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
f980: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
f990: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
f9a0: 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
f9b0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
f9c0: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
f9d0: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
f9e0: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
f9f0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
fa00: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
fa10: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
fa20: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
fa30: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
fa40: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
fa50: 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
fa60: 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
fa70: 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
fa80: 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
fa90: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
faa0: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
fab0: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
fac0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
fad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fae0: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
faf0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
fb00: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
fb10: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
fb20: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
fb30: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
fb40: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
fb50: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
fb60: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
fb70: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
fb80: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
fb90: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
fba0: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
fbb0: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
fbc0: 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
fbd0: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
fbe0: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
fbf0: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
fc00: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
fc10: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
fc20: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
fc30: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
fc40: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
fc50: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
fc60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
fc70: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
fc80: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
fc90: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
fca0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
fcb0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
fcc0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
fcd0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
fce0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
fcf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
fd00: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
fd10: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
fd20: 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
fd30: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
fd40: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
fd50: 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
fd60: 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
fd70: 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
fd80: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
fd90: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
fda0: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
fdb0: 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
fdc0: 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
fdd0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
fde0: 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
fdf0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
fe00: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
fe10: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
fe20: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
fe30: 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
fe40: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
fe50: 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
fe60: 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
fe70: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
fe80: 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
fe90: 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
fea0: 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
feb0: 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
fec0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
fed0: 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
fee0: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
fef0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
ff00: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
ff10: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
ff20: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
ff30: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
ff40: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
ff50: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
ff60: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
ff70: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
ff80: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
ff90: 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
ffa0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
ffb0: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
ffc0: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
ffd0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
ffe0: 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
fff0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
10000 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
10010 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
10020 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
10030 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
10040 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
10050 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
10060 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
10070 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
10080 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
10090 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
100a0 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
100b0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
100c0 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
100d0 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
100e0 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
100f0 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
10100 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
10110 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
10120 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
10130 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
10140 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
10150 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
10160 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
10170 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
10180 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
10190 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
101a0 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
101b0 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
101c0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
101d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
101e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
101f0 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
10200 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
10210 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
10220 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
10230 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
10240 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
10250 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
10260 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
10270 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
10280 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10290 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
102a0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
102b0 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
102c0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
102d0 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
102e0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
102f0 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
10300 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
10310 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
10320 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
10330 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10340 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10350 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
10360 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
10370 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
10380 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
10390 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
103a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
103b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
103c0 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
103d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
103e0 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
103f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
10400 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
10410 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
10420 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
10430 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
10440 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
10450 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
10460 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
10470 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
10480 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
10490 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
104a0 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
104b0 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
104c0 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
104d0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
104e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
104f0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
10500 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
10510 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
10520 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
10530 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
10540 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
10550 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
10560 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
10570 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
10580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
10590 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
105a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
105b0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
105c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
105d0 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
105e0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
105f0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
10600 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
10610 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
10620 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
10630 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
10640 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
10650 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
10660 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
10670 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
10680 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
10690 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
106a0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
106b0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
106c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
106d0 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
106e0 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
106f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
10700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10710 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
10720 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
10730 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
10740 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
10750 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
10760 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
10770 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
10780 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
10790 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
107a0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
107b0 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
107c0 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
107d0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
107e0 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
107f0 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
10800 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
10810 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
10820 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
10830 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
10840 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
10850 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
10860 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
10870 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
10880 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
10890 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
108a0 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
108b0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
108c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
108d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
108e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
108f0 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
10900 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
10910 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
10920 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
10930 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
10940 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
10950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
10960 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
10970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
10980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
10990 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
109a0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
109b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
109c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
109d0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
109e0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
109f0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
10a00 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
10a10 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
10a20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
10a30 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
10a40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
10a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
10a60 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
10a70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
10a80 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
10a90 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
10aa0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
10ab0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
10ac0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
10ad0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
10ae0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
10af0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
10b00 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
10b10 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
10b20 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
10b30 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
10b40 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
10b50 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
10b60 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
10b70 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
10b80 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
10b90 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
10ba0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
10bb0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
10bc0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
10bd0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
10be0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
10bf0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
10c00 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
10c10 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
10c20 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
10c30 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
10c40 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
10c50 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
10c60 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
10c70 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
10c80 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
10c90 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
10ca0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
10cb0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
10cc0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
10cd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
10ce0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
10cf0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
10d00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
10d10 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
10d20 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
10d30 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
10d40 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
10d50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
10d60 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
10d70 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
10d80 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
10d90 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
10da0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
10db0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
10dc0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
10dd0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
10de0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
10df0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
10e00 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
10e10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
10e20 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
10e30 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
10e40 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
10e50 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
10e60 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
10e70 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
10e80 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
10e90 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10ea0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
10eb0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
10ec0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
10ed0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
10ee0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
10ef0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
10f00 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
10f10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
10f20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10f30 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
10f40 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
10f50 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
10f60 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
10f70 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
10f80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
10f90 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
10fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
10fb0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
10fc0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
10fd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
10fe0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
10ff0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
11000 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
11010 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
11020 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
11030 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
11040 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
11050 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
11060 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
11070 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
11080 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
11090 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
110a0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
110b0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
110c0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
110d0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
110e0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
110f0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
11100 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
11110 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
11120 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
11130 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
11140 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
11150 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
11160 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
11170 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
11180 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
11190 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
111a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
111b0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
111c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
111d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
111e0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
111f0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
11200 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
11210 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
11220 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
11230 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
11240 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11250 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
11260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
11270 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
11280 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
11290 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
112a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
112b0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
112c0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
112d0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
112e0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
112f0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
11300 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
11310 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
11320 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
11330 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
11340 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
11350 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
11360 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
11370 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
11380 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
11390 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
113a0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
113b0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
113c0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
113d0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
113e0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
113f0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
11400 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
11410 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
11420 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
11430 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
11440 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
11450 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
11460 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
11470 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
11480 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
11490 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
114a0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
114b0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
114c0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
114d0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
114e0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
114f0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
11500 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
11510 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
11520 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
11530 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
11540 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
11550 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
11560 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
11570 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
11580 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
11590 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
115a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
115b0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
115c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
115d0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
115e0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
115f0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
11600 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
11610 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
11620 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
11630 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
11640 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
11650 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
11660 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
11670 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
11680 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
11690 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
116a0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
116b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
116c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
116d0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
116e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
116f0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
11700 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11710 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
11720 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
11730 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
11740 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
11750 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11760 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
11770 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
11780 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
11790 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
117a0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
117b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
117c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
117d0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
117e0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
117f0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
11800 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
11810 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
11820 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
11830 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
11840 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
11850 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
11860 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
11870 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
11880 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
11890 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
118a0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
118b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
118c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
118d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
118e0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
118f0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
11900 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
11910 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
11920 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
11930 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
11940 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
11950 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
11960 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
11970 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
11980 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
11990 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
119a0 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
119b0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
119c0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
119d0 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
119e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
119f0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
11a00 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
11a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11a20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11a30 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
11a40 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
11a50 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
11a60 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
11a70 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
11a80 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
11a90 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
11aa0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
11ab0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
11ac0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
11ad0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
11ae0 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
11af0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
11b00 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
11b10 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
11b20 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
11b30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11b40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
11b50 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
11b60 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
11b70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
11b80 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
11b90 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
11ba0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
11bb0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
11bc0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
11bd0 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
11be0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
11bf0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
11c00 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
11c10 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
11c20 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
11c30 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
11c40 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
11c50 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
11c60 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
11c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
11c80 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
11c90 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
11ca0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
11cb0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
11cc0 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
11cd0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
11ce0 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
11cf0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
11d00 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
11d10 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
11d20 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
11d30 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
11d40 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
11d50 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
11d60 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
11d70 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
11d80 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
11d90 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
11da0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
11db0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
11dc0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
11dd0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
11de0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
11df0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
11e00 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
11e10 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
11e20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
11e30 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
11e40 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
11e50 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
11e60 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
11e70 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
11e80 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
11e90 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
11ea0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
11eb0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
11ec0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
11ed0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
11ee0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
11ef0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
11f00 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
11f10 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
11f20 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
11f30 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
11f40 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
11f50 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
11f60 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
11f70 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
11f80 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
11f90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
11fa0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
11fb0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
11fc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
11fd0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
11fe0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
11ff0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
12000 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
12010 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
12020 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
12030 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
12040 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
12050 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
12060 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
12070 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
12080 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
12090 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
120a0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
120b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
120c0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
120d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
120e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
120f0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
12100 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
12110 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
12120 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
12130 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
12140 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
12150 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
12160 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
12170 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
12180 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
12190 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
121a0 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
121b0 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
121c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
121d0 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
121e0 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
121f0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
12200 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
12210 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
12220 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
12230 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
12240 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
12250 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
12260 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
12270 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
12280 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
12290 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
122a0 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
122b0 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
122c0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
122d0 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
122e0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
122f0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
12300 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
12310 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
12320 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
12330 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
12340 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
12350 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
12360 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
12370 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
12380 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
12390 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
123a0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
123b0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
123c0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
123d0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
123e0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
123f0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
12400 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
12410 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
12420 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
12430 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
12440 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
12450 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
12460 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
12470 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
12480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12490 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
124a0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
124b0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
124c0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
124d0 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
124e0 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
124f0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
12500 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
12510 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
12520 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
12540 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
12550 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
12560 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
12570 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
12580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
12590 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
125a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
125b0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
125c0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
125d0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
125e0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
125f0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
12600 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
12610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
12620 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
12630 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
12640 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
12650 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
12660 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
12670 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
12680 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
12690 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
126a0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
126b0 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
126c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
126d0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
126e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
126f0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
12700 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
12710 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
12720 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
12730 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
12740 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
12750 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
12760 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
12770 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
12780 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
12790 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
127a0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
127b0 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
127c0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
127d0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
127e0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
127f0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
12800 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
12810 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
12820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
12830 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12840 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
12850 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
12860 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
12870 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
12880 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
12890 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
128a0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
128b0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
128c0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
128d0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
128e0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
128f0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
12900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12910 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
12920 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
12930 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
12940 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
12950 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
12960 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
12970 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
12980 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
12990 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
129a0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
129b0 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  red.)^.*/.int sq
129c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
129d0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
129e0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
129f0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
12a00 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
12a10 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
12a20 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
12a30 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
12a40 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
12a50 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
12a60 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
12a70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
12a80 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
12a90 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
12aa0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
12ab0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
12ac0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
12ad0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
12ae0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
12af0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
12b00 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
12b10 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
12b20 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
12b30 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
12b40 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
12b50 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
12b60 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
12b70 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
12b80 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
12b90 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
12ba0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
12bb0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
12bc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
12bd0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
12be0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
12bf0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
12c00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
12c10 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
12c20 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
12c30 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
12c40 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
12c50 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
12c60 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
12c70 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
12c80 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
12c90 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
12ca0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
12cb0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
12cc0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
12cd0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
12ce0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
12cf0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
12d00 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
12d10 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
12d20 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
12d30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12d40 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
12d50 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
12d60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
12d70 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
12d80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
12d90 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
12da0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
12db0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12dc0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
12dd0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
12de0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
12df0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
12e00 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
12e10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
12e20 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
12e30 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
12e40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
12e50 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
12e60 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
12e70 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
12e80 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
12e90 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
12ea0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
12eb0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12ec0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
12ed0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
12ee0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
12ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
12f00 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
12f10 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
12f20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
12f30 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
12f40 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
12f50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12f60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
12f70 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
12f80 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
12f90 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
12fa0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
12fb0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
12fc0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
12fd0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
12fe0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
12ff0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
13000 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
13010 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
13020 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
13030 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13040 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
13050 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
13060 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
13070 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13080 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
13090 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
130a0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
130b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
130c0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
130d0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
130e0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
130f0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
13100 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13110 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
13120 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
13130 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
13140 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13150 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
13160 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13170 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e  ckquote>.**.** ^
13180 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
13190 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
131a0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
131b0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
131c0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
131d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
131e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
131f0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
13200 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
13210 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
13220 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
13230 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
13240 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
13250 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
13260 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
13270 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
13280 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
13290 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
132a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
132b0 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c  e(),.** it shoul
132c0 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  d pass the resul
132d0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
132e0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
132f0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
13300 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
13310 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
13320 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
13330 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
13340 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
13350 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
13360 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
13370 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
13380 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
13390 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
133a0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
133b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
133c0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
133d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
133e0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
133f0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
13400 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
13410 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
13420 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  ^(The sqlite3_ge
13430 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
13440 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
13450 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
13460 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
13470 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
13480 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
13490 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
134a0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
134b0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
134c0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
134d0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
134e0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
134f0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
13500 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
13510 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
13520 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
13530 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
13540 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
13550 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
13560 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
13570 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
13580 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
13590 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
135a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
135b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
135c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
135d0 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e  rmsg()].)^.*/.in
135e0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
135f0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
13600 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
13610 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
13620 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
13630 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
13640 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
13650 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
13660 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
13670 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
13680 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
13690 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
136a0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
136b0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
136c0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
136d0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
136e0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
136f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
13700 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
13710 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
13720 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
13730 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
13740 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
13750 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
13760 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
13770 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
13780 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
13790 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
137a0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
137b0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
137c0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
137d0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
137e0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
137f0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
13800 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
13810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
13820 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
13830 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
13840 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
13850 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
13860 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
13870 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
13880 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
13890 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
138a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
138b0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
138c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
138d0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
138e0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
138f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13900 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
13910 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
13920 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
13930 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
13940 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
13950 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
13960 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
13970 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
13980 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
13990 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
139a0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
139b0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
139c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
139d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
139e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
139f0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
13a00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
13a10 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
13a20 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
13a30 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
13a40 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
13a50 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
13a60 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
13a70 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
13a80 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
13a90 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
13aa0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
13ab0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
13ac0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
13ad0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
13ae0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
13af0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
13b00 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
13b10 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
13b20 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
13b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
13b40 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
13b50 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
13b60 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
13b70 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
13b80 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
13b90 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
13ba0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13bb0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
13bc0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
13bd0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
13be0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
13bf0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
13c00 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
13c10 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
13c20 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
13c30 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
13c40 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
13c50 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
13c60 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
13c70 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
13c80 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
13c90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
13ca0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
13cb0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
13cc0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
13cd0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
13ce0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
13cf0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
13d00 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
13d10 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
13d20 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
13d30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
13d40 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
13d50 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
13d60 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
13d70 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
13d80 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
13d90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
13da0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
13db0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
13dc0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
13dd0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
13de0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
13df0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
13e00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
13e10 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
13e20 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
13e30 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
13e40 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
13e50 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
13e60 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
13e70 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
13e80 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
13e90 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
13ea0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
13eb0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
13ec0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
13ed0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
13ee0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
13ef0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
13f00 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
13f10 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
13f20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
13f30 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
13f40 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
13f50 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
13f60 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
13f70 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
13f80 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
13f90 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
13fa0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
13fb0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
13fc0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
13fd0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
13fe0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
13ff0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
14000 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
14010 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
14020 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
14030 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
14040 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
14050 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14060 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
14070 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
14080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
14090 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
140a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
140b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
140c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
140d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
140e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
140f0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
14100 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
14110 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
14120 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
14130 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
14140 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14150 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
14160 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
14170 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
14180 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
14190 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
141a0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
141b0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
141c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
141d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
141e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
141f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
14200 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
14210 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
14220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14230 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
14240 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
14250 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
14260 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
14270 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
14280 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
14290 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
142a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
142b0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
142c0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
142d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
142e0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
142f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14300 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
14310 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
14320 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
14330 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
14340 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
14350 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
14360 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
14370 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
14380 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
14390 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
143a0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
143b0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
143c0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
143d0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
143e0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
143f0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
14400 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
14410 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
14420 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
14430 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
14440 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14450 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
14460 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
14470 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
14480 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
14490 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
144a0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
144b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
144c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
144d0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
144e0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
144f0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
14500 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
14510 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
14520 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
14530 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
14540 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
14550 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14560 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
14570 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
14580 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
14590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
145a0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
145b0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
145c0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
145d0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
145e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
145f0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
14600 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
14610 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
14620 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
14630 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
14640 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
14650 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
14660 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
14670 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
14680 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
14690 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
146a0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
146b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
146c0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
146d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
146e0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
146f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
14700 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
14710 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
14720 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
14730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14740 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14750 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
14760 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
14770 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
14780 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
14790 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
147a0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
147b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
147c0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
147d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
147e0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
147f0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
14800 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
14810 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
14820 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
14830 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
14840 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
14850 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
14860 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
14870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
14890 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
148a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
148b0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
148c0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
148d0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
148e0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
148f0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
14900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14910 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
14920 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
14930 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
14940 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
14950 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
14960 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
14970 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
14980 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
14990 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
149a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
149b0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
149c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
149d0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
149e0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
149f0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
14a00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
14a10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14a20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
14a30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
14a40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
14a50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
14a60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
14a70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
14a80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
14a90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
14aa0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
14ab0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
14ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
14ad0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
14ae0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
14af0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
14b00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
14b10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
14b20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
14b30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
14b40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
14b50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
14b60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
14b70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
14b80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
14b90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
14ba0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
14bb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
14bc0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
14bd0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
14be0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
14bf0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
14c00 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
14c10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
14c20 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
14c30 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
14c40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
14c50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14c60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
14c70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14c80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
14c90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
14ca0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
14cb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
14cc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
14cd0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
14ce0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
14cf0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
14d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
14d10 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
14d20 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
14d30 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
14d40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14d50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
14d60 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
14d70 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
14d80 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
14d90 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
14da0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
14db0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
14dc0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
14dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
14de0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
14df0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
14e00 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
14e10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14e20 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
14e30 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
14e40 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
14e50 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
14e60 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14e70 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
14e80 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
14e90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
14eb0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
14ec0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
14ed0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
14ee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
14ef0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
14f00 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
14f10 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
14f20 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
14f30 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
14f40 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
14f50 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
14f60 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
14f70 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
14f80 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
14f90 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
14fa0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
14fb0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
14fc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
14fd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14fe0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
14ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
15000 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
15010 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
15020 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
15030 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
15040 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
15050 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
15060 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
15070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
15080 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
15090 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
150a0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
150b0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
150c0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
150d0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
150e0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
150f0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
15100 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
15110 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
15120 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
15130 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
15140 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
15150 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
15160 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
15170 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
15180 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
15190 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
151a0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
151b0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
151c0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
151d0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
151e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69  ed..**.** The Wi
151f0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
15200 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
15210 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
15220 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
15230 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
15240 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
15250 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
15260 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
15270 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
15280 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
15290 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
152a0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
152b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
152c0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
152d0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
152e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
152f0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
15300 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
15310 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
15320 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
15330 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
15340 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
15350 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
15360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
15370 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
15380 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15390 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
153a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
153b0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
153c0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
153d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
153e0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
153f0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
15400 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
15410 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15420 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
15430 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
15440 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
15450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15460 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
15470 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
15480 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
15490 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
154a0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
154b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
154c0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
154d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
154e0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
154f0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
15500 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
15510 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
15520 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
15530 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
15540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
15550 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
15560 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
15570 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
15580 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
15590 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
155a0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
155b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
155c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
155d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
155e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
155f0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
15600 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
15610 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
15620 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15630 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
15640 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
15650 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
15660 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15670 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15680 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
15690 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
156a0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
156b0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
156c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
156d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
156e0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
156f0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
15700 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
15710 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15720 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
15730 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
15740 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
15750 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
15760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
15770 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
15780 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
15790 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
157a0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
157b0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
157c0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
157d0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
157e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
157f0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
15800 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
15810 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
15820 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
15830 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
15840 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
15850 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
15860 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
15870 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
15880 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
15890 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
158a0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
158b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
158c0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
158d0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
158e0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
158f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15900 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
15910 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
15920 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
15930 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15940 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
15950 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
15960 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
15970 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
15980 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
15990 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
159a0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
159b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
159c0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
159d0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
159e0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
159f0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
15a00 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
15a10 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
15a20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
15a30 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
15a40 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
15a50 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
15a60 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
15a70 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
15a80 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
15a90 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
15aa0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
15ab0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
15ac0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
15ad0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
15ae0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
15af0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
15b00 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
15b10 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
15b20 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
15b30 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
15b40 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
15b50 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
15b60 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
15b70 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
15b80 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
15b90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
15ba0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
15bb0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
15bc0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
15bd0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
15be0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
15bf0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
15c00 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
15c10 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
15c20 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
15c30 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
15c40 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
15c50 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
15c60 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
15c70 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
15c80 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
15c90 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
15ca0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
15cb0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
15cc0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
15cd0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
15ce0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
15cf0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
15d00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
15d10 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
15d20 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
15d30 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
15d40 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
15d50 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
15d60 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
15d70 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
15d80 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
15d90 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
15da0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
15db0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15dc0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
15dd0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
15de0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
15df0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
15e00 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
15e10 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
15e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15e30 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
15e40 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
15e50 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
15e60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
15e70 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
15e80 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
15e90 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
15ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15eb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
15ec0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
15ed0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
15ee0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
15ef0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
15f00 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
15f10 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
15f20 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
15f30 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
15f40 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
15f50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15f60 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
15f70 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
15f80 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
15f90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
15fa0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
15fb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15fc0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
15fd0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
15fe0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
15ff0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
16000 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
16010 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
16020 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
16030 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
16040 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
16050 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
16060 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
16070 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
16080 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
16090 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
160a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
160b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
160c0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
160d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
160e0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
160f0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
16100 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
16110 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
16120 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
16130 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
16140 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
16150 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
16160 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
16170 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
16180 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
16190 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
161a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
161b0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
161c0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
161d0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
161e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
161f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
16200 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
16210 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16220 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
16230 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
16240 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
16250 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
16260 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
16270 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
16280 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
16290 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
162a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
162b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
162c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
162d0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
162e0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
162f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
16300 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16310 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
16320 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
16330 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
16340 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
16350 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
16360 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
16370 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
16380 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
16390 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
163a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
163b0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
163c0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
163d0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
163e0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
163f0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
16400 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
16410 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
16420 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
16430 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
16440 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
16450 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
16460 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
16470 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
16480 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16490 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
164a0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
164b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
164c0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
164d0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
164e0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
164f0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
16500 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
16510 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
16520 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
16530 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
16540 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
16550 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
16560 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
16570 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16580 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
16590 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
165a0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
165b0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
165c0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
165d0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
165e0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
165f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
16600 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
16610 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
16620 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
16630 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
16640 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
16650 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
16660 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
16670 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
16680 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
16690 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
166a0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
166b0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
166c0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
166d0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
166e0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
166f0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
16700 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
16710 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
16720 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
16730 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
16740 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
16750 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
16760 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
16770 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
16780 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
16790 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
167a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
167b0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
167c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
167d0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
167e0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
167f0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
16800 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
16810 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
16820 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
16830 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
16840 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
16850 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
16860 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
16870 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
16880 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
16890 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
168a0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
168b0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
168c0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
168d0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
168e0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
168f0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
16900 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
16910 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
16920 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
16930 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
16940 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
16950 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
16960 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
16970 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
16980 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
16990 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
169a0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
169b0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
169c0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
169d0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
169e0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
169f0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
16a00 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
16a10 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
16a20 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
16a30 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
16a40 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
16a50 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
16a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
16a70 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
16a80 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
16a90 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16aa0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
16ab0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
16ac0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
16ad0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
16ae0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
16af0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
16b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
16b10 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16b20 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
16b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16b40 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
16b50 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
16b60 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
16b70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16b80 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
16b90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16ba0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
16bb0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
16bc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
16bd0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
16be0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
16bf0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
16c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
16c10 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
16c20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
16c30 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
16c40 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
16c50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
16c60 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
16c70 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
16c80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
16c90 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
16ca0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
16cb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
16cc0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
16cd0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
16ce0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16cf0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
16d00 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
16d10 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
16d20 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
16d30 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
16d40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
16d50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
16d60 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
16d70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
16d80 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
16d90 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
16da0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
16db0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
16dc0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
16dd0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
16de0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
16df0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
16e00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
16e10 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
16e20 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
16e30 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
16e40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
16e50 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
16e60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
16e70 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
16e80 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
16e90 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
16ea0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
16eb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
16ec0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
16ed0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
16ee0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
16ef0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
16f00 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
16f10 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
16f20 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
16f30 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
16f40 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
16f50 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
16f60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16f70 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
16f80 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
16f90 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
16fa0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
16fb0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
16fc0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
16fd0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
16fe0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
16ff0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
17000 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
17010 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
17020 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
17030 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
17040 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
17050 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
17060 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
17070 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
17080 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
17090 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
170a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
170b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
170c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
170d0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
170e0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
170f0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
17100 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
17110 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
17120 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
17130 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
17140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17150 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
17160 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
17170 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
17180 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
17190 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
171a0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
171b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
171c0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
171d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
171e0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
171f0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
17200 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
17210 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
17220 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
17230 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
17240 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
17250 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
17260 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
17270 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
17280 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
17290 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
172a0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
172b0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
172c0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
172d0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
172e0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
172f0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
17300 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
17310 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
17320 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
17330 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
17340 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
17350 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
17360 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
17370 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17380 65 74 65 72 2e 20 20 5e 54 68 65 20 35 74 68 20  eter.  ^The 5th 
17390 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
173a0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
173b0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
173c0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
173d0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
173e0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
173f0 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 5e 54   applicable.  ^T
17400 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
17410 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17420 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
17430 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
17440 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
17450 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
17460 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
17470 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
17480 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
17490 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
174a0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
174b0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
174c0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
174d0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
174e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
174f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17500 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
17510 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
17520 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
17530 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
17540 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
17550 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
17560 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17580 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
17590 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
175a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
175b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
175c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
175d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
175e0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
175f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
17600 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17620 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
17630 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
17640 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17650 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17670 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
17680 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
17690 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
176a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
176b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
176c0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
176d0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
176e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
176f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17710 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
17720 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
17730 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
17740 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17750 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17760 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
17770 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
17780 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
17790 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
177a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
177b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
177c0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
177d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
177e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
177f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
17800 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
17810 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
17820 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
17830 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17840 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
17850 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
17860 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17870 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17880 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17890 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
178a0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
178b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
178c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
178d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
178e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
178f0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
17900 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17910 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17920 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17930 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
17940 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
17950 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
17960 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17970 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17980 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
17990 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
179a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
179b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
179c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
179d0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
179e0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
179f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
17a00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17a10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a20 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
17a30 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
17a40 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
17a50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17a60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a70 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
17a80 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
17a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
17aa0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17ab0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17ac0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
17ad0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
17ae0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
17af0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
17b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17b10 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
17b20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
17b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
17b40 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
17b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
17b60 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
17b70 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
17b80 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
17b90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
17bb0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
17bc0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
17bd0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
17be0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17bf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
17c00 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
17c10 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
17c20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
17c30 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
17c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
17c50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
17c60 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
17c70 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
17c80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17c90 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
17ca0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
17cb0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
17cc0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
17cd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17ce0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
17cf0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
17d00 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
17d10 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
17d20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17d30 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
17d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
17d50 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
17d60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17d70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17d80 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
17d90 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
17da0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17db0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17dc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17dd0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
17de0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
17df0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17e00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
17e10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17e20 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
17e30 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
17e40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17e50 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
17e60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17e70 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
17e80 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
17e90 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
17ea0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
17eb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17ec0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
17ed0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
17ee0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
17ef0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
17f00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f10 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
17f20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
17f30 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
17f40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
17f50 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
17f60 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
17f70 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
17f80 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  AL.**.** These r
17f90 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
17fa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17fb0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
17fc0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
17fd0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
17fe0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
17ff0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18000 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
18010 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18020 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
18030 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
18040 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
18050 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
18060 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
18070 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
18080 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
18090 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
180a0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
180b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
180c0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
180d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
180e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
180f0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
18100 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
18110 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
18120 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
18130 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
18140 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
18150 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
18160 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
18170 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
18180 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
18190 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
181a0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
181b0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
181c0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
181d0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
181e0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
181f0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18200 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
18210 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
18220 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
18230 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
18240 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
18250 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
18260 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
18270 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
18280 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
18290 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
182a0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
182b0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
182c0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
182d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
182e0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
182f0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
18300 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
18310 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
18320 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
18330 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
18340 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
18350 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
18360 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
18370 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
18380 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
18390 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
183a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
183b0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
183c0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
183d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
183e0 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
183f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18400 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
18410 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
18420 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
18430 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
18440 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
18450 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
18460 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
18470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
18480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
18490 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
184a0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
184b0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
184c0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
184d0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
184e0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
184f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
18500 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
18510 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
18520 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
18530 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
18540 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
18550 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
18560 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
18570 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
18580 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
18590 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
185a0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
185b0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
185c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
185d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
185e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
185f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
18600 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
18610 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
18620 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
18630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18640 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
18650 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
18660 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
18670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
18680 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
18690 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
186a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
186b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
186c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
186d0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
186e0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
186f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
18700 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
18710 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
18720 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
18730 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
18740 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
18750 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
18760 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
18770 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
18780 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
18790 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
187a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
187b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
187c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
187d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
187e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
187f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
18800 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
18810 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
18820 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
18830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18840 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
18850 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
18860 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
18870 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
18880 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
18890 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
188a0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
188b0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
188c0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
188d0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
188e0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
188f0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
18900 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
18910 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
18920 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
18930 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
18940 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
18950 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
18960 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
18970 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
18980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
18990 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
189a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
189b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
189c0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
189d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
189e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
189f0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
18a00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
18a10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
18a20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
18a30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
18a40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
18a50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
18a60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
18a70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
18a80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
18a90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
18aa0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
18ab0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
18ac0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
18ad0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
18ae0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
18af0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
18b00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
18b10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
18b20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
18b30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
18b40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
18b50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
18b60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
18b70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
18b80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
18b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18ba0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
18bb0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
18bc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
18bd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
18be0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
18bf0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
18c00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
18c10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
18c20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
18c30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
18c40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
18c50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
18c60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
18c70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
18c80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
18c90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
18ca0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
18cb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
18cc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
18cd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
18ce0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
18cf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
18d00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
18d10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
18d20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
18d30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
18d40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
18d50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
18d60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
18d70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
18d80 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ,.** and/or [SQL
18d90 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
18da0 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a  CACHE] flags:)^.
18db0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
18dc0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
18dd0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
18de0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18df0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
18e00 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
18e10 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
18e20 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
18e30 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
18e40 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
18e50 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
18e60 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
18e70 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
18e80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
18e90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
18ea0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
18eb0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
18ec0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
18ed0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
18ee0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
18ef0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
18f00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
18f10 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
18f20 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
18f30 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
18f40 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
18f50 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
18f60 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
18f70 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
18f80 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
18f90 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
18fa0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
18fb0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
18fc0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
18fd0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
18fe0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
18ff0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
19000 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
19010 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
19020 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
19030 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
19040 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
19050 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
19060 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
19070 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
19080 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
19090 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
190a0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
190b0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
190c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
190d0 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
190e0 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
190f0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
19100 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
19110 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
19120 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
19130 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
19140 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  EX],.** [SQLITE_
19150 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
19160 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  ] and/or [SQLITE
19170 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
19180 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65  E] flags,.** the
19190 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
191a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
191b0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
191c0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
191d0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
191e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
191f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
19200 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
19210 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
19220 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
19230 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
19240 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
19250 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
19260 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
19270 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
19280 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
19290 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
192a0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
192b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
192c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
192d0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
192e0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
192f0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
19300 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
19310 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
19320 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
19330 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
19340 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
19350 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
19360 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
19370 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
19380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
19390 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
193a0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
193b0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
193c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
193d0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
193e0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
193f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
19400 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
19410 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
19420 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
19430 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
19440 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
19450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19460 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
19470 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
19480 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
19490 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
194a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  led..**.** ^If t
194b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
194c0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
194d0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
194e0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
194f0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
19500 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
19510 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
19520 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
19530 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
19540 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
19550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19560 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
19570 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
19580 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
19590 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
195a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
195b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
195c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
195d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
195e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
195f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
19600 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
19610 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
19620 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
19630 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
19640 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
19650 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
19660 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
19670 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
19680 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
19690 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
196a0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
196b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
196c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
196d0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
196e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
196f0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
19700 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
19710 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
19720 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
19730 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
19740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19750 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
19760 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
19770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19790 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
197a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
197b0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
197c0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
197d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
197e0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
197f0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
19800 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
19810 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
19820 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
19830 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
19840 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
19850 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
19860 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
19870 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
19880 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
19890 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
198a0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
198b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
198c0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
198d0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
198e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
198f0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
19900 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
19910 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
19920 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
19930 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
19940 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
19950 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
19960 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
19970 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
19980 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
19990 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
199a0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
199b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
199c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
199d0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
199e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
199f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
19a00 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
19a10 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
19a20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
19a30 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
19a40 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
19a50 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
19a60 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
19a70 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
19a80 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
19a90 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
19aa0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
19ab0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
19ac0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
19ad0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
19ae0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
19af0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
19b00 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
19b10 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
19b20 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
19b30 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
19b40 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
19b50 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
19b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
19b70 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
19b80 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
19b90 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
19ba0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
19bb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
19bc0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
19bd0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
19be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19bf0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
19c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
19c10 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
19c20 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
19c30 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
19c40 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
19c50 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
19c60 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
19c70 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
19c80 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
19c90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
19ca0 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
19cb0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
19cc0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
19cd0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
19ce0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
19cf0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
19d00 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
19d10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
19d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
19d30 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
19d40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
19d50 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
19d60 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
19d70 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
19d80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
19d90 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
19da0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
19db0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
19dc0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
19dd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
19de0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
19df0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
19e00 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
19e10 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
19e20 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
19e30 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
19e40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
19e50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
19e60 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
19e70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
19e80 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
19e90 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
19ea0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
19eb0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
19ec0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
19ed0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
19ee0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
19ef0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
19f00 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
19f10 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
19f20 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
19f30 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
19f40 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
19f50 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
19f60 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
19f70 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
19f80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
19f90 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
19fa0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
19fb0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
19fc0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
19fd0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19fe0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
19ff0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
1a000 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
1a010 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
1a020 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1a030 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
1a040 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
1a050 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
1a060 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
1a070 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
1a080 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
1a090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
1a0a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
1a0b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
1a0c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
1a0d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
1a0e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1a0f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
1a100 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
1a110 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
1a120 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1a130 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
1a140 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
1a150 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
1a160 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1a170 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
1a180 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
1a190 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
1a1a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
1a1b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
1a1c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
1a1d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1a1e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1a1f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1a200 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1a210 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1a220 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1a230 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1a240 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1a250 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1a260 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1a270 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1a280 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
1a290 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1a2a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1a2b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1a2c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1a2d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1a2e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1a2f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1a300 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1a310 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1a320 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1a330 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1a340 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1a350 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1a360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1a370 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1a380 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1a390 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1a3a0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1a3b0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1a3c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1a3d0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1a3e0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1a3f0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1a400 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1a410 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1a420 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1a430 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1a440 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1a450 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1a460 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1a470 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1a480 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1a490 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1a4a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1a4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a4c0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1a4d0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1a4e0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1a4f0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1a500 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1a510 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1a520 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1a530 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1a540 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1a550 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1a560 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1a570 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1a580 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1a590 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1a5a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1a5b0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1a5c0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1a5d0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1a5e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1a5f0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1a600 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1a610 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1a620 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1a630 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1a640 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1a650 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1a660 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1a670 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1a680 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1a690 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1a6a0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1a6b0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1a6c0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1a6d0 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
1a6e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1a6f0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1a700 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1a710 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1a720 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1a730 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1a740 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1a750 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1a760 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1a770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1a780 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1a790 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1a7a0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1a7b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1a7c0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1a7d0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1a7e0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1a7f0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1a800 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1a810 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1a820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1a830 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1a840 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1a850 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1a860 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
1a870 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20   limit.)^.**.** 
1a880 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
1a890 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
1a8a0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
1a8b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
1a8c0 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d  ** ^(For the lim
1a8d0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
1a8e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
1a8f0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
1a900 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
1a910 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
1a920 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74  t by a compile-t
1a930 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73  ime C preprocess
1a940 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a  or macro named .
1a950 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
1a960 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a  ITE_MAX_XYZ]..**
1a970 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1a980 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1a990 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1a9a0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
1a9b0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1a9c0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1a9d0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1a9e0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1a9f0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1aa00 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69  he hard upper li
1aa10 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74  mit..**.** Run-t
1aa20 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
1aa30 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
1aa40 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
1aa50 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
1aa60 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
1aa70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1aa80 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1aa90 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1aaa0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1aab0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1aac0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1aad0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1aae0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1aaf0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1ab00 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1ab10 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1ab20 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1ab30 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1ab40 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1ab50 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1ab60 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1ab70 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1ab80 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1ab90 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1aba0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1abb0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1abc0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1abd0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1abe0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1abf0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1ac00 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1ac10 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1ac20 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1ac30 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1ac40 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1ac50 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1ac60 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1ac70 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1ac80 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1ac90 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1aca0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1acb0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1acc0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1acd0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1ace0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1acf0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1ad00 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1ad10 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1ad20 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1ad30 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1ad40 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1ad50 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1ad60 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1ad70 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
1ad80 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1ad90 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1ada0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1adb0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1adc0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1add0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
1ade0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1adf0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
1ae00 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
1ae10 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1ae20 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
1ae30 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
1ae40 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
1ae50 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
1ae60 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1ae70 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
1ae80 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
1ae90 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
1aea0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
1aeb0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
1aec0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
1aed0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
1aee0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
1aef0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
1af00 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
1af10 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  l>.** ^(<dt>SQLI
1af20 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1af30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1af40 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1af50 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1af60 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
1af70 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  <dd>)^.**.** ^(<
1af80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1af90 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1afa0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1afb0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1afc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
1afd0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
1afe0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1aff0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1b000 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b010 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1b020 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1b030 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1b040 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1b050 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1b060 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1b070 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1b080 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1b090 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1b0a0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1b0b0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1b0c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b0d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1b0e0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1b0f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1b100 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1b110 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1b120 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
1b130 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1b140 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1b150 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1b160 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b170 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1b180 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1b190 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1b1a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1b1b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1b1c0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1b1d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b1e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1b1f0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1b200 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1b210 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1b220 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1b230 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1b240 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1b260 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1b270 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b280 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1b290 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1b2a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
1b2b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1b2c0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
1b2d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1b2e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1b2f0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
1b300 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f  ed databases].</
1b310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 3c 64 74 3e 53  dd>.**.** ^<dt>S
1b320 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1b330 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1b340 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b350 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1b360 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1b370 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
1b380 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
1b390 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
1b3a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b3b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1b3c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1b3d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b3e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1b3f0 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1b400 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1b410 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1b420 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1b430 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1b440 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1b450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b460 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1b470 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1b480 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1b490 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1b4a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b4b0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1b4c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1b4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b4e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1b4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1b500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b510 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1b530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b540 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1b550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1b560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b570 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1b580 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1b590 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1b5a0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b5c0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1b5d0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1b5e0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1b5f0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1b600 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1b610 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1b620 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1b630 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1b640 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1b650 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1b660 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1b670 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1b680 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1b690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1b6a0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1b6b0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1b6c0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1b6d0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1b6e0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1b6f0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1b700 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1b710 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1b720 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1b730 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1b740 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1b750 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1b760 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1b770 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1b780 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1b790 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1b7a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b7b0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1b7c0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1b7d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1b7e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1b7f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b800 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1b810 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b820 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1b830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1b840 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1b850 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1b860 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b870 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1b880 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1b890 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1b8a0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1b8b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1b8c0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1b8d0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1b8e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b8f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1b900 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1b910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1b920 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1b930 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1b940 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1b950 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1b960 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1b970 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1b980 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1b990 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1b9a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1b9b0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1b9c0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1b9d0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1b9e0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1b9f0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1ba00 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1ba10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ba20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1ba30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1ba40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1ba50 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1ba60 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1ba70 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1ba80 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1ba90 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1baa0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1bab0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1bac0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1bad0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1bae0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1baf0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1bb00 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1bb10 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1bb20 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1bb30 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1bb40 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1bb50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1bb60 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1bb70 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1bb80 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1bb90 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1bba0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1bbb0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1bbc0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1bbd0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1bbe0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1bbf0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1bc00 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1bc10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1bc20 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1bc30 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1bc40 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1bc50 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1bc60 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1bc70 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1bc80 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1bc90 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1bca0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1bcb0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1bcc0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1bcd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1bce0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1bcf0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1bd00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bd10 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1bd20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1bd30 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1bd40 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1bd50 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1bd60 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1bd70 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1bd80 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1bd90 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1bda0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1bdb0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1bdc0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1bdd0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1bde0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1bdf0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1be00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1be10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1be20 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1be30 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1be40 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1be50 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1be60 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1be70 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1be80 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1be90 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1bea0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1beb0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1bec0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1bed0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1bee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1bef0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1bf00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1bf10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1bf20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1bf30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1bf40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1bf50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1bf60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1bf70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1bf80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1bf90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1bfa0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1bfb0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1bfc0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1bfd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1bfe0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1bff0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1c000 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1c010 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1c020 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1c030 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1c040 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1c050 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1c060 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1c070 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1c080 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1c090 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1c0a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1c0b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1c0c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1c0d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1c0e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1c0f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1c100 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1c110 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1c120 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1c130 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1c140 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1c150 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1c160 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65  n.  ^If the sche
1c170 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1c180 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1c190 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1c1a0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1c1b0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1c1c0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1c1d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1c1e0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1c1f0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1c200 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1c210 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1c220 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1c230 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1c240 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c250 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1c260 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1c270 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1c280 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1c290 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1c2a0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1c2b0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1c2c0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1c2d0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1c2e0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1c2f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1c300 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1c310 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1c320 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c330 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1c340 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1c350 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1c360 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1c370 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1c380 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1c390 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1c3a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c3b0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1c3c0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1c3d0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1c3e0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1c3f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1c400 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1c410 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1c420 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1c430 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1c440 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1c450 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1c460 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1c470 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1c480 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1c490 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1c4a0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1c4b0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1c4c0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1c4d0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1c4e0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  i>.** ^If the va
1c4f0 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65  lue of a [parame
1c500 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
1c510 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45  eter] in the WHE
1c520 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a  RE clause might.
1c530 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75  ** change the qu
1c540 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
1c550 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74  tatement, then t
1c560 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  he statement may
1c570 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1c580 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20  ally recompiled 
1c590 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64  (as if there had
1c5a0 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63   been a schema c
1c5b0 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69  hange) on the fi
1c5c0 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rst .** [sqlite3
1c5d0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
1c5e0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
1c5f0 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  ge to the .** [s
1c600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c610 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1c620 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  the [parameter].
1c630 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
1c640 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
1c650 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1c660 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1c670 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1c680 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1c690 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1c6a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1c6b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1c6c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1c6d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1c6e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1c6f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1c700 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1c710 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1c720 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1c730 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1c740 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1c750 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1c760 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1c770 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1c780 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1c790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c7a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c7b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1c7c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1c7d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c7e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1c7f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1c800 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1c810 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1c820 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1c830 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1c840 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1c850 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1c860 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1c870 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1c880 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1c890 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1c8a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1c8b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1c8c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1c8d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1c8e0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1c8f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c900 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1c910 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1c920 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1c930 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1c940 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1c950 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1c960 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1c970 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1c980 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1c990 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1c9a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1c9b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1c9c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1c9d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1c9e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1c9f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1ca00 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1ca10 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1ca20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1ca30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1ca40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1ca50 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1ca60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1ca70 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1ca80 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1ca90 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1caa0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1cab0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1cac0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1cad0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1cae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1caf0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1cb00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1cb10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1cb20 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1cb30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1cb40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1cb50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1cb60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cb70 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1cb80 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1cb90 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1cba0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1cbb0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1cbc0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1cbd0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1cbe0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1cbf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1cc00 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1cc10 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1cc20 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1cc30 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1cc40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1cc50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1cc60 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
1cc70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1cc80 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1cc90 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1cca0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
1ccb0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1ccc0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
1ccd0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1cce0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1ccf0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1cd00 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1cd10 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1cd20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1cd30 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1cd40 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1cd50 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1cd60 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1cd70 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1cd80 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1cd90 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1cda0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1cdb0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
1cdc0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
1cdd0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
1cde0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
1cdf0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1ce00 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1ce10 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1ce20 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1ce30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1ce40 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1ce50 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1ce60 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1ce70 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1ce80 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1ce90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1cea0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1ceb0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1cec0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1ced0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1cee0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1cef0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1cf00 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1cf10 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1cf20 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1cf30 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
1cf40 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1cf50 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1cf60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1cf70 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1cf80 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1cf90 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1cfa0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1cfb0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1cfc0 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1cfd0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1cfe0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1cff0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d000 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1d010 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1d020 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1d030 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d040 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1d050 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1d060 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1d070 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1d080 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
1d090 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
1d0a0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1d0b0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1d0c0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
1d0d0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
1d0e0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
1d0f0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
1d100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
1d110 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
1d120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1d130 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
1d140 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
1d150 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1d160 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1d170 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1d180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d190 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
1d1a0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
1d1b0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
1d1c0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
1d1d0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
1d1e0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
1d1f0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
1d200 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
1d210 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
1d220 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1d230 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1d240 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1d250 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d260 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1d270 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1d280 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1d290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1d2a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1d2b0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1d2c0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1d2d0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1d2e0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1d2f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1d300 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1d310 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1d320 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1d330 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1d340 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1d350 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1d360 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1d370 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1d380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d390 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1d3a0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1d3b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1d3c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1d3d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1d3e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1d3f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1d400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1d410 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1d420 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1d430 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1d440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1d450 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1d460 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1d470 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1d480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1d490 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1d4a0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1d4b0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1d4c0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1d4d0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1d4e0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1d4f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1d500 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1d510 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1d520 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1d530 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1d540 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d550 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1d560 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1d570 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1d580 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1d590 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1d5a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1d5b0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1d5c0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1d5d0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1d5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1d5f0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1d600 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1d610 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1d620 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1d630 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1d640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1d650 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1d660 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1d670 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1d680 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1d690 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1d6a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1d6b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1d6c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1d6d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d6e0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1d6f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1d700 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1d710 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1d720 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1d730 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1d740 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1d750 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1d760 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1d770 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1d780 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1d790 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1d7a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1d7b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1d7c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d7d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1d7e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1d7f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1d800 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1d810 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1d820 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1d830 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1d840 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1d850 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1d860 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1d870 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1d880 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1d890 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1d8a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1d8b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1d8c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1d8d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1d8e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1d8f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1d900 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  ifer.)^  ^The va
1d910 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1d920 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1d930 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1d940 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1d950 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1d960 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1d970 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1d980 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1d990 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1d9a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
1d9b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1d9c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1d9d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1d9e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
1d9f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1da00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1da10 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1da20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1da30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1da40 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
1da50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
1da60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1da70 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1da80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1da90 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
1daa0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1dab0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1dac0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
1dad0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1dae0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1daf0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1db00 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1db10 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1db20 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1db30 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1db40 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1db50 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
1db60 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1db70 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1db80 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1db90 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1dba0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dbb0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1dbc0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
1dbd0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1dbe0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1dbf0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1dc00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
1dc10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1dc20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1dc30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1dc40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1dc50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1dc60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1dc70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1dc80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
1dc90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1dca0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1dcb0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1dcc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
1dcd0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1dce0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1dcf0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1dd00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1dd10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1dd20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1dd30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1dd40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1dd50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1dd60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1dd70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1dd80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1dd90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
1dda0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1ddb0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1ddc0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1ddd0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1dde0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1ddf0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1de00 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1de10 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
1de20 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1de30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1de40 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1de50 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1de60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1de70 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1de80 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1de90 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1dea0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1deb0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1dec0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1ded0 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69  h it. ^If the fi
1dee0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1def0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1df00 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1df10 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1df20 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1df30 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1df40 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1df50 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1df60 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1df70 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1df80 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
1df90 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1dfa0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1dfb0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1dfc0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1dfd0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1dfe0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1dff0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1e000 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1e010 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e020 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1e030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e040 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
1e050 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
1e060 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
1e070 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
1e080 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
1e090 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
1e0a0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1e0b0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1e0c0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1e0d0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1e0e0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1e0f0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1e100 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1e110 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1e120 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1e130 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1e140 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1e150 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1e160 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e170 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1e180 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1e190 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
1e1a0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1e1b0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1e1c0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1e1d0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1e1e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
1e1f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
1e200 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e210 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
1e220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1e230 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
1e240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1e250 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
1e260 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
1e270 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
1e280 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
1e290 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
1e2a0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
1e2b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
1e2c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
1e2d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1e2e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
1e2f0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
1e300 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
1e310 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
1e320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e330 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
1e340 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
1e350 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
1e360 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1e370 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1e380 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
1e390 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1e3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1e3b0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1e3c0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
1e3d0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1e3e0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1e3f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e400 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
1e410 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1e420 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1e430 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
1e440 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
1e450 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
1e460 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
1e470 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1e480 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1e490 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1e4a0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
1e4b0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1e4c0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
1e4d0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
1e4e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1e4f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1e500 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1e510 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e520 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1e530 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1e540 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1e550 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1e560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1e570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1e580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1e590 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1e5a0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1e5b0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1e5c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1e5d0 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1e5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1e5f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e600 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1e610 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1e620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1e630 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1e640 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1e650 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1e660 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1e670 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e680 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1e690 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1e6a0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1e6b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1e6c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1e6d0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1e6e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1e6f0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1e700 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1e710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1e720 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1e730 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1e740 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1e750 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e760 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1e770 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1e780 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1e790 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1e7a0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
1e7b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1e7c0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1e7d0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1e7e0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1e7f0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1e800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e810 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1e820 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1e830 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1e840 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1e850 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1e860 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1e870 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1e880 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1e890 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1e8a0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1e8b0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1e8c0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1e8d0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
1e8e0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
1e8f0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1e900 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1e910 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
1e920 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
1e930 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
1e940 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1e950 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1e960 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
1e970 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
1e980 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1e990 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1e9a0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
1e9b0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
1e9c0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1e9d0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
1e9e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1e9f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1ea00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1ea10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ea20 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1ea30 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1ea40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ea50 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1ea60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ea70 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1ea80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1ea90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1eaa0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1eab0 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
1eac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1ead0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
1eae0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1eaf0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
1eb00 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
1eb10 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1eb20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1eb30 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
1eb40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1eb50 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1eb60 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1eb70 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1eb80 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1eb90 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1eba0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1ebb0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1ebc0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1ebd0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1ebe0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1ebf0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1ec00 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1ec10 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1ec20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1ec30 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
1ec40 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1ec50 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1ec60 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1ec70 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1ec80 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
1ec90 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1eca0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1ecb0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1ecc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ecd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1ece0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1ecf0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1ed00 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1ed10 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1ed20 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1ed30 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1ed40 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1ed50 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1ed60 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1ed70 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1ed80 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1ed90 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1eda0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1edb0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1edc0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1edd0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1ede0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1edf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1ee00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1ee10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1ee20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1ee30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1ee40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1ee50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1ee60 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1ee70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ee80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1ee90 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1eea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1eeb0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1eec0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1eed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1eee0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1eef0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1ef00 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1ef10 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1ef20 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1ef30 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1ef40 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1ef50 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1ef60 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1ef70 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1ef80 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1ef90 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1efa0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1efb0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1efc0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1efd0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1efe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1eff0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1f000 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1f010 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1f020 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1f030 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f040 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1f050 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1f060 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1f070 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f080 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1f090 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1f0a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1f0b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1f0c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f0d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1f0e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f0f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f100 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1f110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f120 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1f130 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1f140 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1f150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f160 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1f170 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1f180 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
1f190 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1f1a0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1f1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1f1c0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1f1d0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1f1e0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1f1f0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1f200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f210 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
1f220 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1f230 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1f240 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1f250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1f260 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1f270 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f290 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1f2a0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
1f2b0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1f2c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1f2d0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1f2e0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1f2f0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1f300 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
1f310 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1f320 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1f330 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1f340 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1f350 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1f360 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1f370 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
1f380 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1f390 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1f3a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f3b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1f3c0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1f3d0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
1f3e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1f3f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1f400 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1f410 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1f420 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1f430 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1f440 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1f450 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1f460 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1f470 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f490 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f4a0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1f4b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1f4c0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1f4d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f4e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1f4f0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1f500 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
1f510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1f520 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f530 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1f540 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1f550 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f560 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1f570 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1f580 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1f590 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
1f5a0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
1f5b0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
1f5c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1f5d0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1f5e0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1f5f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f600 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1f610 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1f620 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1f630 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f640 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1f650 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1f660 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1f670 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1f680 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1f690 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
1f6a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1f6b0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1f6c0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1f6d0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1f6e0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1f6f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1f700 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1f710 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1f720 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1f730 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1f740 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1f750 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1f760 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1f770 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1f780 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1f790 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1f7a0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1f7b0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1f7c0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1f7d0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1f7e0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1f7f0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1f800 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1f810 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1f820 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
1f830 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f840 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1f850 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1f860 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1f870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1f880 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1f890 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1f8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1f8b0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1f8c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
1f8d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f8e0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1f8f0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1f900 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
1f910 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
1f920 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1f930 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
1f940 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
1f950 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
1f960 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
1f970 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
1f980 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f990 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1f9a0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1f9b0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1f9c0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1f9d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
1f9e0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1f9f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1fa00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1fa10 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1fa20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1fa30 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1fa40 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1fa50 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1fa60 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1fa70 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
1fa80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1fa90 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
1faa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fab0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1fac0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
1fad0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1fae0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
1faf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1fb00 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
1fb10 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
1fb20 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
1fb30 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
1fb40 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
1fb50 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
1fb60 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
1fb70 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
1fb80 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
1fb90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1fba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
1fbb0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
1fbc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fbd0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
1fbe0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
1fbf0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
1fc00 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
1fc10 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
1fc20 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1fc30 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1fc40 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1fc50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1fc60 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
1fc70 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
1fc80 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
1fc90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1fca0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
1fcb0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
1fcc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1fcd0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1fce0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
1fcf0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
1fd00 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
1fd10 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
1fd20 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
1fd30 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
1fd40 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1fd50 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1fd60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fd70 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
1fd80 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
1fd90 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1fda0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
1fdb0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
1fdc0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
1fdd0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
1fde0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
1fdf0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
1fe00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
1fe10 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
1fe20 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
1fe30 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
1fe40 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1fe50 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1fe60 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
1fe70 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
1fe80 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
1fe90 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
1fea0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1feb0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1fec0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1fed0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
1fee0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1fef0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
1ff00 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
1ff10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
1ff20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1ff30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
1ff40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1ff50 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
1ff60 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
1ff70 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
1ff80 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
1ff90 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1ffa0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
1ffb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1ffc0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1ffd0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1ffe0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1fff0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20000 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
20010 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
20020 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
20030 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
20040 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
20050 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
20060 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
20070 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20080 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20090 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
200a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
200b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
200c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
200d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
200e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
200f0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20100 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20110 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20130 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20140 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
20150 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20160 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
20170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20180 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20190 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
201a0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
201b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
201c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
201d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
201e0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
201f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
20210 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
20220 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
20230 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
20240 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
20250 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20260 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
20270 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
20280 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20290 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
202a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
202b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
202c0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
202d0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
202e0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
202f0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
20300 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
20310 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
20320 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
20330 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
20340 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
20350 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
20360 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20370 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
20380 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
20390 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
203a0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
203b0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
203c0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
203d0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
203e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
203f0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
20400 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
20410 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
20420 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
20430 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
20440 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
20450 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
20460 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
20470 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
20480 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
20490 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
204a0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
204b0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
204c0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
204d0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
204e0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
204f0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20500 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20510 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
20520 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
20530 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
20540 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
20550 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
20560 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
20570 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
20580 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
20590 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
205a0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
205b0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
205c0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
205d0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
205e0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
205f0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
20600 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
20610 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
20620 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
20630 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
20640 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
20650 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
20660 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
20670 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
20680 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
20690 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
206a0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
206b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
206c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
206d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
206e0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
206f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
20700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20710 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
20720 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
20730 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
20740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
20750 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
20760 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
20770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20780 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
20790 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
207a0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
207b0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
207c0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
207d0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
207e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
207f0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
20800 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
20810 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
20820 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
20830 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
20840 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
20850 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
20860 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
20870 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
20880 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
20890 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
208a0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
208b0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
208c0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
208d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
208e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
208f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20900 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
20910 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
20920 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
20930 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
20940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20950 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
20960 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
20970 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
20980 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20990 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
209a0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
209b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
209c0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
209d0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
209e0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
209f0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
20a00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
20a10 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
20a20 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
20a30 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
20a40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
20a50 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
20a60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
20a70 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
20a80 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
20a90 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
20aa0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
20ab0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
20ac0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
20ad0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
20ae0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
20af0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
20b00 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
20b10 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
20b20 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
20b30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
20b40 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
20b50 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
20b60 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
20b70 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
20b80 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
20b90 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
20ba0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
20bb0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
20bc0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
20bd0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
20be0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
20bf0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
20c00 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
20c10 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
20c20 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
20c30 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
20c40 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
20c50 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
20c60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
20c70 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
20c80 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
20c90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
20ca0 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
20cb0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
20cc0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
20cd0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
20ce0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
20cf0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20d00 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
20d10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
20d20 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
20d30 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
20d40 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
20d50 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
20d60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
20d70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
20d80 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
20d90 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
20da0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
20db0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
20dc0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
20dd0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
20de0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
20df0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
20e00 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
20e10 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
20e20 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
20e30 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20e40 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20e50 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
20e60 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
20e70 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
20e80 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
20e90 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
20ea0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
20eb0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
20ec0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
20ed0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
20ee0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
20ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
20f00 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
20f10 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
20f20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
20f30 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
20f40 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
20f50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20f60 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
20f70 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
20f80 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
20f90 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
20fa0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
20fb0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
20fc0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
20fd0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
20fe0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
20ff0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
21000 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
21010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21020 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
21030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21040 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
21050 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
21060 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
21070 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
21080 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21090 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
210a0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
210b0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
210c0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
210d0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
210e0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
210f0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
21100 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
21110 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21120 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
21130 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
21140 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21150 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
21160 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
21170 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
21180 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21190 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
211a0 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
211b0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
211c0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
211d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
211e0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
211f0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
21200 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
21210 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
21220 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
21230 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
21240 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
21250 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
21260 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
21270 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
21280 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
21290 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
212a0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
212b0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
212c0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
212d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
212e0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
212f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
21300 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
21310 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21320 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
21330 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
21340 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
21350 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
21360 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
21370 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
21380 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
21390 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
213a0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
213b0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
213c0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
213d0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
213e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
213f0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
21400 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
21410 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
21420 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
21430 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21440 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21450 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
21460 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
21470 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
21480 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
21490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
214a0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
214b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
214c0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
214d0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
214e0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
214f0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
21500 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
21510 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
21520 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
21530 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
21540 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
21550 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
21560 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
21570 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
21580 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
21590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
215a0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65  ata_count(P) the
215b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
215c0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20  ns in the.** of 
215d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
215e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
215f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74  ement] P..*/.int
21600 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21610 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21620 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21630 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
21640 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
21650 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21660 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21670 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
21680 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
21690 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
216a0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
216b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
216c0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
216d0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
216e0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
216f0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
21700 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
21710 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
21720 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
21730 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
21740 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
21750 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
21760 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
21770 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
21780 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
21790 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
217a0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
217b0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
217c0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
217d0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
217e0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
217f0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
21800 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
21810 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
21820 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
21830 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
21840 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
21850 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
21860 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
21870 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
21880 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
21890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
218a0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
218b0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
218c0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
218d0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
218e0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
218f0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
21900 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
21910 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
21920 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
21930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
21940 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
21950 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
21960 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
21970 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
21980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21990 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
219a0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
219b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
219c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
219d0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
219e0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
219f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
21a00 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
21a10 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
21a20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
21a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21a40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
21a50 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
21a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21a70 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
21a80 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
21a90 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
21aa0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
21ab0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
21ac0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
21ad0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
21ae0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
21af0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
21b00 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
21b10 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
21b20 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
21b30 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
21b40 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
21b50 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
21b60 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
21b70 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
21b80 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
21b90 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
21ba0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
21bb0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
21bc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
21bd0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
21be0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
21bf0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
21c00 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
21c10 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
21c20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
21c30 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
21c40 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
21c50 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
21c60 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
21c70 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
21c80 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
21c90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
21ca0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
21cb0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
21cc0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
21cd0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
21ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
21cf0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
21d00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
21d10 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
21d20 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
21d30 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
21d40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
21d50 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
21d60 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
21d70 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
21d80 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
21d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21da0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
21db0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
21dc0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
21dd0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
21de0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
21df0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
21e00 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
21e10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
21e20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21e30 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
21e40 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
21e50 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
21e60 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
21e70 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
21e80 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
21e90 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
21ea0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
21eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21ec0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
21ed0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
21ee0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
21ef0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
21f00 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
21f10 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
21f20 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
21f30 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
21f40 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
21f50 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
21f60 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
21f70 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
21f80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
21f90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
21fa0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
21fb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
21fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
21fd0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
21fe0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
21ff0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22000 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
22010 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
22020 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
22030 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
22040 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22050 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22060 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
22070 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
22080 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
22090 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
220a0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
220b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
220c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
220d0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
220e0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
220f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
22100 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
22110 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
22120 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22130 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
22140 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
22150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22160 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
22170 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
22180 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
22190 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
221a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
221b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
221c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
221d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
221e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
221f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
22200 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
22210 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
22220 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
22230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22240 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
22250 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
22260 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
22270 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
22280 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
22290 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
222a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
222b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65   string..** ^The
222c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
222d0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
222e0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
222f0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
22300 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
22310 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
22320 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22330 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
22340 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
22350 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
22360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22370 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
22380 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
22390 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
223a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
223b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
223c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
223d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
223e0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
223f0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
22400 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
22410 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
22420 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
22430 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
22440 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
22450 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
22460 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
22470 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
22480 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
224a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
224b0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
224c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
224d0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
224e0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
224f0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
22500 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
22510 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65  f UTF-8..** ^The
22520 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22530 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
22540 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
22550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
22560 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
22570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
22580 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
22590 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
225a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
225b0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
225c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
225d0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
225e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
225f0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
22600 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
22620 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
22630 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22640 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22650 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
22660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
22670 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
22680 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
22690 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
226a0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
226b0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
226c0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
226d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
226e0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
226f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
22700 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
22710 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
22720 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
22730 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
22740 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
22750 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
22760 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
22770 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
22780 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
22790 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
227a0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
227b0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
227c0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
227d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
227e0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
227f0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
22800 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
22810 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
22820 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
22830 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
22840 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
22850 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
22860 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
22870 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
22880 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
22890 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
228a0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
228b0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
228c0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
228d0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
228e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
228f0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
22900 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
22910 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22920 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
22930 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
22940 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22950 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
22960 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22970 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22980 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22990 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
229a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
229b0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
229c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
229d0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
229e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
229f0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
22a00 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
22a10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
22a20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
22a30 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
22a40 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
22a50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
22a60 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
22a70 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
22a80 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
22a90 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
22aa0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22ab0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
22ac0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
22ad0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
22ae0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
22af0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
22b00 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
22b10 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
22b20 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
22b30 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
22b40 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
22b50 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
22b60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
22b70 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22b80 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
22b90 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
22ba0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22bb0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
22bc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
22bd0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
22be0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
22bf0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
22c00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
22c10 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
22c20 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
22c30 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
22c40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
22c50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22c60 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
22c70 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
22c80 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
22c90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
22ca0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
22cb0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
22cc0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
22cd0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
22ce0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
22cf0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
22d00 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
22d10 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
22d20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
22d30 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
22d40 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
22d50 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
22d60 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
22d70 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
22d80 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
22d90 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
22da0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
22db0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
22dc0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
22dd0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
22de0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
22df0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
22e00 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
22e10 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
22e20 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
22e30 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
22e40 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
22e50 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
22e60 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
22e70 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
22e80 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
22e90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22ea0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
22eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22ec0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
22ed0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79  lidated..** ^(Ty
22ee0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
22ef0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
22f00 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
22f10 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
22f20 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
22f30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
22f40 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
22f50 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
22f60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
22f70 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
22f80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
22f90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
22fa0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
22fb0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
22fc0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
22fd0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
22fe0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
22ff0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23000 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
23010 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
23020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23030 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
23040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23050 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23060 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
23070 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
23080 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
23090 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
230a0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
230b0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
230c0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
230d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
230e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
230f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23100 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
23110 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
23120 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
23130 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
23140 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
23150 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
23160 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
23170 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
23180 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
23190 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
231a0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
231b0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
231c0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
231d0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
231e0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
231f0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
23200 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23210 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23220 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
23230 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
23240 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
23250 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
23260 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
23270 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
23280 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
23290 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
232a0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
232b0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
232c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  lidated..**.** ^
232d0 28 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20  (The safest and 
232e0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
232f0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
23300 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
23310 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
23320 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23330 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
23340 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
23350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23360 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
23370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23380 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
23390 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
233a0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
233b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
233c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
233d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
233e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
233f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
23400 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23410 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
23420 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  >)^.**.** In oth
23430 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
23440 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
23450 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
23460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23470 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
23480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23490 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
234a0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
234b0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
234c0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
234d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
234e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
234f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
23500 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23510 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
23520 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
23530 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
23540 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
23550 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
23560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23570 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
23580 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23590 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
235a0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
235b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
235c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
235d0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
235e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
235f0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
23600 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
23610 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
23620 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
23630 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
23640 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
23650 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
23660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
23680 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23690 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
236a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
236b0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
236c0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
236d0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
236e0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
236f0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
23700 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
23710 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
23720 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
23730 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
23740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23750 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
23760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
23770 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
23780 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
23790 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
237a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
237b0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
237c0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
237d0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
237e0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
237f0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
23800 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
23810 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
23820 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
23830 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
23840 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
23850 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
23860 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
23870 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
23880 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
23890 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
238a0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
238b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
238c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
238d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
238e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
238f0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
23900 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
23910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
23920 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
23930 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23940 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
23950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
23960 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23970 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
23980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
23990 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
239a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
239b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
239c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
239d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
239e0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
239f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
23a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23a10 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
23a20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
23a30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23a40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
23a50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23a60 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23a80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23a90 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
23aa0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
23ab0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
23ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23ad0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
23ae0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
23af0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
23b00 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
23b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23b20 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
23b30 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
23b40 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
23b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23b60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74  .** ^If the stat
23b70 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
23b80 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
23b90 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
23ba0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
23bb0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
23bc0 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75  urned. ^If execu
23bd0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
23be0 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
23bf0 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
23c00 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
23c10 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
23c20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23c30 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
23c40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
23c50 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
23c60 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
23c70 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
23c80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
23c90 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20  ^If the virtual 
23ca0 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
23cb0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
23cc0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
23cd0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
23ce0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
23cf0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
23d00 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
23d10 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
23d20 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
23d30 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20  .** ^Incomplete 
23d40 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
23d50 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
23d60 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
23d70 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
23d80 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
23d90 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
23da0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
23db0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
23dc0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
23dd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23de0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
23df0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
23e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23e10 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
23e20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
23e30 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
23e40 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
23e50 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
23e60 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
23e70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23e80 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
23e90 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
23ea0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
23eb0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
23ec0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
23ed0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
23ee0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
23ef0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
23f00 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
23f10 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
23f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
23f30 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
23f40 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
23f50 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
23f60 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
23f70 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
23f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
23f90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
23fa0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
23fb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23fc0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
23fd0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
23fe0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
23ff0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
24000 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
24010 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24020 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
24030 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24040 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
24050 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
24060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
24070 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
24080 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
24090 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
240a0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
240b0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
240c0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
240d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
240e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
240f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
24100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
24110 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
24120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24130 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
24140 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
24150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24160 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
24170 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
24180 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
24190 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
241a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
241b0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
241c0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
241d0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
241e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
241f0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
24200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24210 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
24220 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
24230 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24250 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
24260 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
24270 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
24280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24290 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
242a0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
242b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
242c0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
242d0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
242e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
242f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
24300 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e  * ^These two fun
24310 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
24320 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
24330 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24340 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
24350 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
24360 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
24370 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
24380 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
24390 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
243a0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
243b0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
243c0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
243d0 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
243e0 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68  the.** two is th
243f0 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
24400 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d  rameter, the nam
24410 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
24420 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  ) function or.**
24430 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
24440 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
24450 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
24460 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
24470 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20  d UTF-16.** for 
24480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24490 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
244a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
244b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
244c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
244d0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
244e0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
244f0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
24500 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
24510 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
24520 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
24530 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
24540 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
24550 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
24560 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
24570 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
24580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24590 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
245a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
245b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
245c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
245d0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
245e0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
245f0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
24600 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
24610 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
24620 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
24630 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
24640 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
24650 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
24660 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
24670 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
24680 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
24690 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  .  ^Any attempt 
246a0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
246b0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
246c0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
246d0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
246e0 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
246f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
24700 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24710 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
24720 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
24730 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
24740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24750 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
24760 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
24770 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
24780 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
24790 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
247a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
247b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
247c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
247d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
247e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
247f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
24800 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24810 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
24820 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
24830 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
24840 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
24850 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
24860 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
24870 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
24880 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24890 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
248a0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
248b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
248c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
248d0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
248e0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
248f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
24900 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
24910 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24920 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
24930 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
24940 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
24950 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
24960 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
24970 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
24980 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
24990 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
249a0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
249b0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
249c0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
249d0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
249e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
249f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24a00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
24a10 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
24a20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
24a30 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
24a40 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
24a50 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
24a60 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
24a70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24a80 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
24a90 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
24aa0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
24ab0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
24ac0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
24ad0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
24ae0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
24af0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
24b00 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
24b10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
24b20 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
24b30 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
24b40 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
24b50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
24b60 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
24b70 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
24b80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
24b90 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
24ba0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
24bb0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
24bc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
24bd0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
24be0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
24bf0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
24c00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
24c10 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
24c20 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
24c30 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
24c40 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
24c50 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
24c60 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
24c70 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
24c80 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
24c90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
24ca0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24cb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
24cc0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
24cd0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
24ce0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
24cf0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
24d00 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
24d10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
24d20 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
24d30 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
24d40 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
24d50 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
24d60 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
24d70 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
24d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
24d90 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
24da0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
24db0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
24dc0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
24dd0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
24de0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
24df0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
24e00 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
24e10 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
24e20 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
24e30 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
24e40 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
24e50 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
24e60 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
24e70 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
24e80 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
24e90 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
24ea0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
24eb0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
24ec0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
24ed0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
24ee0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
24ef0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
24f00 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
24f10 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
24f20 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
24f30 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
24f40 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
24f50 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
24f60 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
24f70 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
24f80 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
24f90 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
24fa0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
24fb0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
24fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
24fd0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
24fe0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
24ff0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
25000 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
25010 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
25020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
25030 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
25040 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
25050 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
25060 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
25070 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
25080 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
25090 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
250a0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
250b0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
250c0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
250d0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
250e0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
250f0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25100 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25110 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
25120 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
25130 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
25140 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
25150 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
25160 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25170 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
25180 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c   ^The first appl
25190 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
251a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
251b0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
251c0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
251d0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
251e0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
251f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25200 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25210 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75  ame..** ^Subsequ
25220 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
25230 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25240 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
25250 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
25260 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
25270 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25280 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
25290 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
252a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
252b0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
252c0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
252d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
252e0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
252f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
25300 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
25310 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
25320 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
25330 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
25340 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
25350 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
25360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25370 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
25380 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
25390 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
253a0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
253b0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
253c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
253d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
253e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
253f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25400 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
25410 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
25420 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
25430 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
25440 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
25450 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25460 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25470 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
25480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
25490 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
254a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
254b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
254c0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
254d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
254e0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
254f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
25500 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
25510 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
25520 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
25530 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
25540 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
25550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25580 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
25590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
255a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
255b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
255c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
255d0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
255e0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
255f0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
25600 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
25610 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
25620 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
25630 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
25640 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
25650 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
25660 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
25670 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
25680 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25690 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
256a0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
256b0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
256c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
256d0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
256e0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
256f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25710 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
25720 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
25730 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25740 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
25750 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
25760 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
25770 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
25780 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
25790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
257a0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
257b0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
257c0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
257d0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
257e0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
257f0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
25800 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
25810 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
25820 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
25830 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
25840 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
25850 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
25860 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
25870 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
25880 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
25890 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
258a0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
258b0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
258c0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
258d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
258e0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
258f0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
25900 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
25910 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
25920 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
25930 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
25940 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
25950 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
25960 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
25970 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25980 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25990 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
259a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
259b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
259c0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
259d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
259e0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
259f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
25a00 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
25a10 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
25a20 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
25a30 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
25a40 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
25a50 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
25a60 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
25a70 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
25a80 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
25a90 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
25aa0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
25ab0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
25ac0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
25ad0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
25ae0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
25af0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
25b00 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
25b10 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
25b20 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
25b30 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25b40 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
25b50 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
25b60 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
25b70 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
25b80 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
25b90 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
25ba0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
25bb0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
25bc0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
25bd0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
25be0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
25bf0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
25c00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c10 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
25c20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c30 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
25c40 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
25c50 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
25c60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
25c70 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
25c80 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
25c90 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
25ca0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
25cb0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
25cc0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
25cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25ce0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
25cf0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
25d00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
25d10 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
25d20 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
25d30 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
25d40 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
25d50 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
25d60 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
25d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25d80 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
25d90 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
25da0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
25db0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25dc0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
25dd0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
25de0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
25df0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
25e00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25e10 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
25e20 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
25e30 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
25e40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
25e50 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
25e60 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
25e70 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
25e80 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
25e90 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
25ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
25eb0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
25ec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25ed0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
25ee0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
25ef0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
25f00 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
25f10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
25f20 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
25f30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
25f40 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
25f50 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
25f60 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
25f70 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
25f80 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
25f90 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
25fa0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
25fb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
25fc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
25fd0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
25fe0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
25ff0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
26000 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
26010 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
26020 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
26030 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
26040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
26050 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
26060 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
26070 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
26080 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
26090 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
260a0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
260b0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
260c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
260d0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
260e0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
260f0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
26100 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
26110 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
26120 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
26130 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
26140 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
26150 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
26160 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
26170 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
26180 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
26190 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
261a0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
261b0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
261c0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
261d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
261e0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
261f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
26200 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
26210 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
26220 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
26230 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
26240 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
26250 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
26260 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
26270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
26280 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
26290 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
262a0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
262b0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
262c0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
262d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
262e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
262f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26300 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
26310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26320 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
26330 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26340 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
26350 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
26360 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
26370 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
26380 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
26390 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
263a0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
263b0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
263c0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
263d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
263e0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
263f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26400 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
26410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26420 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
26430 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
26440 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
26450 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
26460 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
26470 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
26480 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
26490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
264a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
264b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
264c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
264d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
264e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
264f0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26500 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26520 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
26530 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
26540 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26550 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
26560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26570 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26580 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26590 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
265a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
265b0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
265c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
265d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
265e0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
265f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26610 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26620 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
26630 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69  **.** Implementi
26640 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
26650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
26660 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
26670 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
26680 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
26690 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
266a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
266b0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
266c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
266d0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
266e0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
266f0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
26700 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
26710 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
26720 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
26730 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
26740 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
26750 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
26760 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
26770 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
26780 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
26790 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
267a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
267b0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
267c0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
267d0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
267e0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
267f0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
26800 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
26810 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26820 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
26830 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
26840 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
26850 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
26860 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
26870 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
26880 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
26890 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
268a0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
268b0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
268c0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
268d0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
268e0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
268f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
26900 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
26910 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
26920 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
26930 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
26940 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
26950 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
26960 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26970 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
26980 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
26990 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
269a0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
269b0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
269c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
269d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
269e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
269f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
26a00 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
26a10 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
26a20 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
26a30 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
26a40 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
26a50 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
26a60 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
26a70 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
26a80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26a90 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
26aa0 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
26ab0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
26ac0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
26ad0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
26ae0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
26af0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
26b00 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
26b10 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
26b20 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
26b30 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
26b40 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
26b50 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
26b60 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
26b70 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
26b80 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
26b90 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
26ba0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
26bb0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
26bc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26bd0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
26be0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
26bf0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
26c00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26c10 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
26c20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
26c30 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
26c40 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
26c50 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
26c60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
26c70 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
26c80 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
26c90 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
26ca0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
26cb0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
26cc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
26cd0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
26ce0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
26cf0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
26d00 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
26d10 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
26d20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
26d30 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
26d40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
26d50 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
26d60 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
26d70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26d80 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
26d90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
26da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
26db0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
26dc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
26dd0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
26de0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
26df0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
26e00 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
26e10 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
26e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26e30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
26e40 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26e50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26e60 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
26e70 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
26e80 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
26e90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
26ea0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
26eb0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
26ec0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
26ed0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
26ee0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
26ef0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26f00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26f10 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
26f20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
26f30 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
26f40 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
26f50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
26f60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
26f70 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
26f80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26f90 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
26fa0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
26fb0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
26fc0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
26fd0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
26fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
26ff0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
27000 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
27010 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27020 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
27030 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27040 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
27050 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
27060 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
27070 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
27080 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
27090 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
270a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
270b0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
270c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
270d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
270e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
270f0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
27100 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
27110 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
27120 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
27130 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
27140 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
27150 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
27160 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
27170 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
27180 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
27190 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
271a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
271b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
271c0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
271d0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
271e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
271f0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
27200 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
27210 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
27220 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
27230 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
27240 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
27250 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
27260 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
27270 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
27280 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
27290 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
272a0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
272b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
272c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
272d0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
272e0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
272f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
27300 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
27310 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
27320 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
27330 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
27340 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
27350 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
27360 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
27370 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
27380 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
27390 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
273a0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
273b0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
273c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
273d0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
273e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
273f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27400 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
27410 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
27420 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
27430 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
27440 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
27450 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
27460 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
27470 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27480 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74  tion. ^If no met
27490 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
274a0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
274b0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
274c0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
274d0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
274e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
274f0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
27500 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
27510 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
27520 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
27530 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
27540 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
27550 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
27560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
27570 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27580 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
27590 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
275a0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
275b0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
275c0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
275d0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
275e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
275f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27600 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27610 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
27620 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
27630 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
27640 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
27650 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
27660 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
27670 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20  stroyed..** ^If 
27680 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
27690 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
276a0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
276b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
276c0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
276d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
276e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
276f0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
27700 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
27710 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
27720 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
27730 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
27740 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
27750 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
27760 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
27770 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
27780 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
27790 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
277a0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
277b0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
277c0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
277d0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
277e0 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20  ime.  ^The only 
277f0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
27800 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
27810 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
27820 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
27830 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
27840 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
27850 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
27860 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
27870 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
27880 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
27890 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
278a0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
278b0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
278c0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
278d0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
278e0 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a  parameters].)^.*
278f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27900 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
27910 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27920 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
27930 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
27940 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
27950 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
27960 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
27970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27980 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
27990 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
279a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
279b0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
279c0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
279d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
279e0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
279f0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
27a00 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
27a10 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
27a20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
27a30 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
27a40 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
27a50 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
27a60 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
27a70 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
27a80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
27a90 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
27aa0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
27ab0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
27ac0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
27ad0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
27ae0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
27af0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
27b00 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
27b10 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
27b20 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
27b30 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
27b40 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
27b50 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
27b60 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
27b70 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
27b80 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
27b90 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
27ba0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
27bb0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
27bc0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
27bd0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
27be0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
27bf0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
27c00 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
27c10 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
27c20 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
27c30 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
27c40 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
27c50 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
27c60 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
27c70 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
27c80 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
27c90 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
27ca0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
27cb0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
27cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
27cd0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
27ce0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
27cf0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
27d00 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
27d10 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
27d20 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
27d30 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27d40 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
27d50 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
27d60 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
27d70 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
27d80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
27d90 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
27da0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
27db0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27dc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
27dd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27de0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
27df0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27e00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
27e10 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
27e20 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
27e30 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
27e40 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
27e50 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
27e60 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
27e70 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
27e80 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
27e90 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
27ea0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
27eb0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
27ec0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
27ed0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
27ee0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
27ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
27f00 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
27f10 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
27f20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
27f30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27f40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
27f50 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
27f60 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
27f70 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
27f80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
27f90 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
27fa0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
27fb0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
27fc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
27fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
27fe0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
27ff0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
28000 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
28010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28020 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28030 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
28040 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
28050 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
28060 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
28070 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
28080 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
28090 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
280a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
280b0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
280c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
280d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
280e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
280f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28100 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
28110 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
28120 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
28130 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
28140 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28150 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28170 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
28180 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
28190 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
281a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
281b0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
281c0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
281d0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
281e0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
281f0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
28200 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
28210 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
28220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28230 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
28240 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
28250 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
28260 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
28270 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
28280 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
28290 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
282a0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
282b0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
282c0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
282d0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
282e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
282f0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
28300 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
28310 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
28320 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
28330 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28340 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
28350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28360 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
28370 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
28380 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
28390 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
283a0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
283b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
283c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
283d0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
283e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
283f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
28400 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
28410 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
28420 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
28430 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
28440 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
28450 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
28460 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
28470 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
28480 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28490 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
284a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
284b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
284c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
284d0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
284e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
284f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28500 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
28510 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
28520 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
28530 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
28540 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
28550 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
28560 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
28570 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
28580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28590 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
285a0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
285b0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
285c0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
285d0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
285e0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
285f0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
28600 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
28610 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
28620 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
28630 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
28640 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
28650 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28660 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
28670 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28680 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
28690 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
286a0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
286b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
286c0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
286d0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
286e0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
286f0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
28700 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
28710 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
28720 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
28730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28740 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
28750 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
28760 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
28770 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
28780 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
28790 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
287a0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
287b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
287c0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
287d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
287e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
287f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28800 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28810 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
28820 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
28830 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
28840 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
28850 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
28860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28870 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
28880 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
28890 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
288a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
288b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
288c0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
288d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
288e0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
288f0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
28900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28910 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28920 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
28930 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
28940 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
28950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28960 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
28970 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
28980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28990 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
289a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
289b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
289c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
289d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
289e0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
289f0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
28a00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28a10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28a20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28a30 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
28a40 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
28a50 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
28a60 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
28a70 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28a80 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
28a90 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
28aa0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
28ab0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
28ac0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
28ad0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
28ae0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
28af0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
28b00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
28b10 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28b20 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28b30 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
28b40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
28b50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
28b60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28b70 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
28b80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
28b90 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
28ba0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
28bb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
28bc0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
28bd0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
28be0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
28bf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
28c00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28c10 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28c20 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
28c30 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
28c40 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
28c50 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
28c60 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
28c70 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
28c80 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
28c90 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
28ca0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
28cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
28cc0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
28cd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
28ce0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28cf0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28d00 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
28d10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
28d20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
28d30 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
28d40 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
28d50 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
28d60 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
28d70 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
28d80 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
28d90 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
28da0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
28db0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
28dc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
28dd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28de0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
28df0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
28e00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
28e10 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
28e20 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
28e30 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
28e40 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
28e50 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
28e60 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
28e70 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
28e80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
28e90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28ea0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
28eb0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
28ec0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
28ed0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
28ee0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
28ef0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
28f00 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
28f10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
28f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
28f30 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
28f40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
28f50 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
28f60 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
28f70 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28f80 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
28f90 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
28fa0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
28fb0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
28fc0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
28fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
28fe0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
28ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29000 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29010 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29020 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
29030 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29040 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29050 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
29060 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
29070 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29080 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
29090 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
290a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
290b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
290c0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
290d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
290e0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
290f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
29100 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
29110 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
29120 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
29130 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
29140 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
29150 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
29160 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
29170 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
29180 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
29190 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
291a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
291b0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
291c0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
291d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
291e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
291f0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
29200 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
29210 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
29220 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
29230 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
29240 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
29250 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
29260 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
29270 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
29280 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
29290 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
292a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
292b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
292c0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
292d0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
292e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
292f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
29300 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29310 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
29320 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29330 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29340 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
29350 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
29360 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
29370 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
29380 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29390 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
293a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
293b0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
293c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
293d0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
293e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
293f0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
29400 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
29410 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
29420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29430 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
29440 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
29450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29460 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
29470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29490 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
294a0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
294b0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
294c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
294d0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
294e0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
294f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29500 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
29510 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
29520 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
29530 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
29540 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29550 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29560 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
29570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29580 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
29590 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
295a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
295b0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
295c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
295d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
295e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
295f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29600 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
29610 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29620 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29630 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29640 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29650 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
29660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29670 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29680 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
29690 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
296a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
296b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
296c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
296d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
296e0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
296f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29700 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
29710 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
29720 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
29730 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ences.**.** Thes
29740 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
29750 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
29760 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
29770 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64  ces to the.** [d
29780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29790 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
297a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
297b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
297c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
297d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
297e0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
297f0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
29800 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
29810 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29820 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
29830 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29840 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
29850 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
29860 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29870 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e  collation16(). ^
29880 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
29890 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
298a0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
298b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
298c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  nt..**.** ^The t
298d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
298e0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
298f0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
29900 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
29910 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
29920 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
29930 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
29940 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
29950 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
29960 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
29970 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
29980 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
29990 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
299a0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
299b0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
299c0 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
299d0 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a  pectively. ^The.
299e0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
299f0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
29a00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
29a10 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
29a20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
29a30 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
29a40 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
29a50 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
29a60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
29a70 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
29a80 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
29a90 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
29aa0 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
29ab0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
29ac0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
29ad0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
29ae0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
29af0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
29b00 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
29b10 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
29b20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
29b30 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
29b40 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
29b50 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
29b60 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55  t.  ^If it is NU
29b70 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
29b80 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
29b90 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
29ba0 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
29bb0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
29bc0 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
29bd0 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d  e)..** ^Each tim
29be0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
29bf0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
29c00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
29c10 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
29c20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
29c30 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
29c40 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
29c50 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
29c60 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
29c70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29c80 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
29c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29ca0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
29cb0 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20   ^The remaining 
29cc0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
29cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
29ce0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
29cf0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
29d00 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
29d10 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
29d20 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
29d30 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
29d40 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
29d50 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
29d60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
29d70 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
29d80 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
29d90 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
29da0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
29db0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
29dc0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
29dd0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
29de0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
29df0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
29e00 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
29e10 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
29e20 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
29e30 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
29e40 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
29e50 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
29e60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
29e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
29e80 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
29e90 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
29ea0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
29eb0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
29ec0 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
29ed0 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
29ee0 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
29ef0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
29f00 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65  lation.  ^The de
29f10 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
29f20 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
29f30 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
29f40 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
29f50 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
29f60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29f70 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
29f80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
29f90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29fa0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f  ion_v2()..** ^Co
29fb0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
29fc0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
29fd0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
29fe0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
29ff0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
2a000 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2a010 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2a020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a030 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2a040 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2a050 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2a060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2a070 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a080 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2a090 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2a0a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2a0b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a0c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a0d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a0e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a0f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2a100 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2a110 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2a120 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a130 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a140 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2a150 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a160 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2a170 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2a180 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2a190 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2a1a0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2a1b0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2a1c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2a1d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2a1e0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2a1f0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2a200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a210 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2a220 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2a230 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2a240 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2a250 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2a260 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2a270 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2a280 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2a290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a2a0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
2a2b0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
2a2c0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
2a2d0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2a2e0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2a2f0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2a300 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2a310 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2a320 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2a330 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2a340 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2a350 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2a360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
2a370 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2a380 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
2a390 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2a3a0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
2a3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a3c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
2a3d0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2a3e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a3f0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
2a400 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
2a410 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
2a420 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
2a430 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2a440 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
2a450 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
2a460 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
2a470 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2a480 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
2a490 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
2a4a0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2a4b0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2a4c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
2a4d0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
2a4e0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2a4f0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
2a500 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
2a510 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2a520 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
2a530 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2a540 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a550 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2a560 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2a570 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2a580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a590 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2a5a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2a5b0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2a5c0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a5d0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2a5e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2a5f0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2a600 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2a610 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2a620 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2a630 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2a640 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2a650 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2a660 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2a670 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2a680 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2a690 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2a6a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a6b0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2a6c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2a6d0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2a6e0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
2a6f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2a700 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
2a710 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
2a720 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
2a730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2a740 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
2a750 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2a760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
2a770 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2a780 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a790 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
2a7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a7b0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2a7c0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2a7d0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2a7e0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2a7f0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2a800 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2a810 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a820 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2a830 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2a840 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2a850 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2a860 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2a870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2a880 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2a890 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2a8a0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2a8b0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2a8c0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2a8d0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2a8e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2a8f0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2a900 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2a910 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2a920 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2a930 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2a940 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2a950 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2a980 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2a990 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2a9a0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2a9b0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2a9c0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2a9d0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2a9e0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2a9f0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2aa00 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2aa10 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2aa20 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2aa30 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2aa40 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2aa50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2aa60 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2aa70 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2aa80 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2aa90 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2aaa0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2aab0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2aac0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2aad0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2aae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2aaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2ab00 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2ab10 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2ab20 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2ab30 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2ab40 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2ab50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ab60 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2ab70 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2ab80 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Time.**.** ^The
2ab90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2aba0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
2abb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2abc0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2abd0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2abe0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2abf0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2ac00 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2ac10 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2ac20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72  .** ^If the oper
2ac30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2ac40 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2ac50 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2ac60 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2ac70 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2ac80 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2ac90 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2aca0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2acb0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68  rest second. ^Th
2acc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2acd0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2ace0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2acf0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2ad00 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2ad10 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2ad20 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2ad30 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2ad40 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2ad50 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2ad60 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2ad70 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2ad80 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
2ad90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2ada0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2adb0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2adc0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
2add0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
2ade0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  iles.**.** ^If t
2adf0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
2ae00 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
2ae10 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
2ae20 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
2ae30 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
2ae40 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
2ae50 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2ae60 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2ae70 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2ae80 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
2ae90 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
2aea0 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
2aeb0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
2aec0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
2aed0 79 2e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  y.  ^If this var
2aee0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
2aef0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2af00 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
2af10 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
2af20 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
2af30 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
2af40 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
2af50 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
2af60 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
2af70 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
2af80 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
2af90 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
2afa0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
2afb0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2afc0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2afd0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
2afe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2aff0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
2b000 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2b010 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
2b020 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
2b030 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
2b040 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2b050 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
2b060 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
2b070 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
2b080 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
2b090 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2b0a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
2b0b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
2b0c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2b0d0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
2b0e0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
2b0f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2b100 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2b110 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
2b120 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
2b130 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
2b140 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
2b150 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2b160 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2b170 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
2b180 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
2b190 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2b1a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
2b1b0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
2b1c0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
2b1d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2b1e0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
2b1f0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
2b200 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
2b210 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2b220 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
2b230 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
2b240 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
2b250 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2b260 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
2b270 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
2b280 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
2b290 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
2b2a0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
2b2b0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
2b2c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2b2d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2b2e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2b2f0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
2b300 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
2b310 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2b320 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
2b330 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2b340 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
2b350 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
2b360 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
2b370 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b380 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
2b390 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
2b3a0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
2b3b0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
2b3c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2b3d0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
2b3e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b3f0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
2b400 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
2b410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b420 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
2b430 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
2b440 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
2b450 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
2b460 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
2b470 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
2b480 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2b490 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
2b4a0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
2b4b0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2b4c0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
2b4d0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
2b4e0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
2b4f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
2b500 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
2b510 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
2b520 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
2b530 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
2b540 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2b550 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
2b560 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
2b570 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
2b580 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2b590 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
2b5a0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
2b5b0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
2b5c0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
2b5d0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
2b5e0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
2b5f0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
2b600 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
2b610 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
2b620 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2b630 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
2b640 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
2b650 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
2b660 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
2b670 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
2b680 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
2b690 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
2b6a0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
2b6b0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2b6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
2b6d0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
2b6e0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
2b6f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b700 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2b710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b720 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2b730 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
2b740 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
2b750 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
2b760 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
2b770 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2b780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b790 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2b7a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2b7b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b7c0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2b7d0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
2b7e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b7f0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
2b800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b810 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
2b820 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
2b830 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
2b840 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b850 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
2b860 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
2b870 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
2b880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b890 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
2b8a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
2b8b0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
2b8c0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
2b8d0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
2b8e0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
2b8f0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2b900 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2b910 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2b920 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2b930 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
2b940 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
2b950 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2b960 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b970 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
2b980 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b990 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
2b9a0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
2b9b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2b9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
2b9d0 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
2b9e0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
2b9f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2ba00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ba10 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
2ba20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2ba30 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2ba40 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
2ba50 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
2ba60 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
2ba70 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
2ba80 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
2ba90 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
2baa0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
2bab0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
2bac0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2bad0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
2bae0 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
2baf0 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
2bb00 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
2bb10 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
2bb20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2bb30 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
2bb40 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
2bb50 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
2bb60 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
2bb70 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2bb80 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2bb90 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2bba0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2bbb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2bbc0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2bbd0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2bbe0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2bbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
2bc00 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
2bc10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2bc20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2bc30 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2bc40 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2bc50 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
2bc60 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
2bc70 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2bc80 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2bc90 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2bca0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2bcb0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2bcc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2bcd0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2bce0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
2bcf0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2bd00 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2bd10 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2bd20 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2bd30 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2bd40 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2bd50 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
2bd60 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
2bd70 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
2bd80 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2bd90 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
2bda0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2bdb0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2bdc0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2bdd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2bde0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2bdf0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
2be00 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
2be10 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
2be20 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
2be30 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2be40 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2be50 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2be60 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
2be70 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
2be80 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
2be90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
2bea0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2beb0 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
2bec0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2bed0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
2bee0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
2bef0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
2bf00 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2bf10 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
2bf20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
2bf30 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2bf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2bf50 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2bf60 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2bf70 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
2bf80 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
2bf90 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
2bfa0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
2bfb0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
2bfc0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
2bfd0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2bfe0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2bff0 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
2c000 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
2c010 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2c020 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c030 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2c040 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2c050 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2c060 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2c070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2c080 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2c090 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
2c0a0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
2c0b0 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
2c0c0 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
2c0d0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
2c0e0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2c0f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
2c100 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
2c110 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2c120 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
2c130 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
2c140 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
2c150 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
2c160 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
2c170 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
2c180 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
2c190 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
2c1a0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2c1b0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2c1c0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2c1d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2c1e0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2c1f0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2c200 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
2c210 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
2c220 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2c230 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
2c240 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
2c250 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
2c260 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
2c270 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
2c280 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
2c290 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
2c2a0 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
2c2b0 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
2c2c0 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
2c2d0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
2c2e0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
2c2f0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
2c300 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
2c310 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
2c320 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
2c330 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
2c340 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
2c350 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
2c360 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
2c370 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
2c380 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
2c390 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
2c3a0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
2c3b0 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
2c3c0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
2c3d0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2c3e0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2c3f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2c400 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2c410 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
2c420 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
2c430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
2c440 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  losed..** ^The r
2c450 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2c460 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2c470 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2c480 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
2c490 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
2c4a0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
2c4b0 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
2c4c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2c4d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2c4e0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2c4f0 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
2c500 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2c510 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
2c520 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
2c530 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
2c540 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2c550 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
2c560 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
2c570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c580 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
2c590 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2c5a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2c5b0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2c5c0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2c5d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2c5e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
2c5f0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2c600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c610 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
2c620 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2c630 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
2c640 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
2c650 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2c660 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2c670 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
2c680 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2c690 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
2c6a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2c6b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2c6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c6d0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2c6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2c6f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2c700 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2c710 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2c720 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2c730 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2c740 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2c750 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2c760 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2c770 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2c780 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2c790 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2c7a0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2c7b0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
2c7c0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
2c7d0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2c7e0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
2c7f0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
2c800 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2c810 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
2c820 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2c830 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2c840 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
2c850 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
2c860 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
2c870 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2c880 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
2c890 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
2c8a0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
2c8b0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
2c8c0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
2c8d0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
2c8e0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
2c8f0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2c900 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
2c910 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
2c920 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
2c930 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2c940 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2c950 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2c960 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2c970 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
2c980 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
2c990 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2c9a0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
2c9b0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
2c9c0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
2c9d0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
2c9e0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
2c9f0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
2ca00 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2ca10 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2ca20 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2ca30 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2ca40 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2ca50 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2ca60 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2ca70 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2ca80 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2ca90 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
2caa0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2cab0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
2cac0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
2cad0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
2cae0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
2caf0 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
2cb00 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
2cb10 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
2cb20 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
2cb30 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
2cb40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2cb50 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2cb60 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2cb70 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2cb80 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2cb90 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2cba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cbb0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2cbc0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2cbd0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2cbe0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2cbf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cc00 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2cc10 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2cc20 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2cc30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2cc40 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2cc50 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2cc60 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2cc70 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2cc80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cc90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2cca0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2ccb0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2ccc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2ccd0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2cce0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2ccf0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2cd00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2cd10 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
2cd20 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
2cd30 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
2cd40 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2cd50 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
2cd60 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2cd70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cd80 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2cd90 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2cda0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
2cdb0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2cdc0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2cdd0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2cde0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2cdf0 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2ce00 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
2ce10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2ce20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2ce30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
2ce40 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
2ce50 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
2ce60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
2ce70 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
2ce80 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2ce90 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2cea0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
2ceb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2cec0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2ced0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2cee0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2cef0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2cf00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2cf10 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2cf20 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2cf30 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2cf40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cf50 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2cf60 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2cf70 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2cf80 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2cf90 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2cfa0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2cfb0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2cfc0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
2cfd0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
2cfe0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2cff0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2d000 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2d010 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2d020 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2d030 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2d040 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2d050 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2d060 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2d070 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2d080 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2d090 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2d0a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
2d0b0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
2d0c0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
2d0d0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
2d0e0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
2d0f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2d100 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2d110 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
2d130 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
2d140 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
2d150 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
2d160 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
2d170 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
2d180 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
2d190 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
2d1a0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
2d1b0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2d1c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
2d1d0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
2d1e0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
2d1f0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
2d200 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2d210 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
2d220 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2d230 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
2d240 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2d250 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2d260 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2d270 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2d280 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2d290 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2d2a0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2d2b0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2d2c0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2d2d0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2d2e0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2d2f0 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2d300 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2d310 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
2d320 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2d330 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2d340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d350 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2d360 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
2d370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d380 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2d390 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2d3a0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
2d3b0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
2d3c0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
2d3d0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
2d3e0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
2d3f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
2d400 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2d410 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
2d420 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
2d430 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
2d440 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
2d450 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
2d460 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
2d470 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
2d480 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
2d490 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2d4a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d4b0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2d4c0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2d4d0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2d4e0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2d4f0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2d500 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2d510 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2d520 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2d530 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
2d540 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
2d550 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
2d560 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2d570 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
2d580 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
2d590 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
2d5a0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
2d5b0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
2d5c0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
2d5d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66  y SQLite..** ^If
2d5e0 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
2d5f0 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
2d600 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20  sted that would 
2d610 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f  exceed the.** so
2d620 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
2d630 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2d640 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
2d650 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d  oked one or.** m
2d660 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
2d670 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
2d680 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
2d690 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  ation is perform
2d6a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c  ed..**.** ^The l
2d6b0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2d6c0 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66  soft" because if
2d6d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2d6e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63  e_memory()].** c
2d6f0 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69  annot free suffi
2d700 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
2d710 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
2d720 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
2d730 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
2d740 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
2d750 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
2d760 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
2d770 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
2d780 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f  ** ^A negative o
2d790 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2d7a0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2d7b0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2d7c0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2d7d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2d7e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2d7f0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2d800 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2d810 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  xhausted..** ^Th
2d820 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2d830 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2d840 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2d850 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
2d860 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2d870 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2d880 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d890 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2d8a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2d8b0 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2d8c0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2d8d0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2d8e0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2d8f0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20  otification.)^  
2d900 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2d910 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2d920 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2d930 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2d940 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2d950 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2d960 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2d970 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2d980 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2d990 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2d9a0 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2d9b0 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2d9c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2d9d0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2d9e0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2d9f0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2da00 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2da10 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2da20 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2da30 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2da40 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2da50 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2da60 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2da70 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2da80 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2da90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2daa0 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2dab0 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2dac0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2dad0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2dae0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2daf0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2db00 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2db10 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2db20 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2db30 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
2db40 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
2db50 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
2db60 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
2db70 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
2db80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2db90 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2dba0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2dbb0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2dbc0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2dbd0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2dbe0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2dbf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2dc00 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2dc10 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2dc20 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2dc30 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
2dc40 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
2dc50 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
2dc60 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
2dc70 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
2dc80 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
2dc90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2dca0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
2dcb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2dcc0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
2dcd0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
2dce0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2dcf0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2dd00 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2dd10 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2dd20 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
2dd30 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
2dd40 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
2dd50 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
2dd60 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
2dd70 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
2dd80 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
2dd90 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2dda0 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
2ddb0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
2ddc0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 29 5e 0a  e references.)^.
2ddd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2dde0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2ddf0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
2de00 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
2de10 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
2de20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
2de30 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
2de40 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
2de50 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
2de60 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79  arameters.** may
2de70 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2de80 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74  ^Metadata is ret
2de90 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
2dea0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
2deb0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
2dec0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
2ded0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
2dee0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
2def0 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f  function. ^Any o
2df00 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2df10 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2df20 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2df30 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2df40 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2df50 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2df60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b  ..**.** ^(<block
2df70 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2df80 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2df90 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2dfa0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2dfb0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2dfc0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2dfd0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2dfe0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2dff0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2e000 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2e010 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2e020 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2e030 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2e040 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2e050 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2e060 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2e070 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2e080 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2e090 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2e0a0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2e0b0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2e0c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2e0d0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2e0e0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2e0f0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2e100 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2e110 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2e120 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2e130 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2e140 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2e150 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   ^The memory poi
2e160 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2e170 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2e180 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2e190 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
2e1a0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
2e1b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2e1c0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
2e1d0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
2e1e0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
2e1f0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
2e200 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
2e210 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
2e220 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
2e230 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2e240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2e250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2e260 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
2e270 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
2e280 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
2e290 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
2e2a0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2e2b0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
2e2c0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
2e2d0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2e2e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2e2f0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
2e300 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2e310 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20  ed column. ^(If 
2e320 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
2e330 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2e340 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ed [INTEGER PRIM
2e350 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c  ARY KEY] column,
2e360 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2e370 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2e380 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
2e390 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
2e3a0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
2e3b0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
2e3c0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
2e3d0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
2e3e0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
2e3f0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
2e400 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
2e410 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
2e420 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
2e430 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
2e440 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
2e450 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
2e460 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
2e470 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
2e480 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2e490 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
2e4a0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
2e4b0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
2e4c0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
2e4d0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
2e4e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2e4f0 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
2e500 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
2e510 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2e520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2e530 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
2e540 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
2e550 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  msg()).)^.**.** 
2e560 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c  ^This API is onl
2e570 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2e580 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2e590 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2e5a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2e5b0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2e5c0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2e5d0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2e5e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e5f0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2e600 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2e610 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2e620 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2e630 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2e640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2e650 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2e660 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2e670 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2e680 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2e690 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2e6a0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2e6b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2e6c0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2e6d0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2e6e0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2e6f0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2e700 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2e710 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2e720 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2e730 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2e740 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2e750 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2e760 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2e770 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2e780 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2e790 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2e7a0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2e7b0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2e7c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2e7d0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2e7e0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2e7f0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2e800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e810 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2e820 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2e830 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2e840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e850 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2e860 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  on.**.** ^This i
2e870 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61  nterface loads a
2e880 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
2e890 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20  on library from 
2e8a0 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a  the named file..
2e8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e8c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e8d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
2e8e0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
2e8f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65  n.** SQLite exte
2e900 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
2e910 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
2e920 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a  ile zFile..**.**
2e930 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e   ^The entry poin
2e940 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e  t is zProc..** ^
2e950 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20  zProc may be 0, 
2e960 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2e970 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
2e980 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66  try point.** def
2e990 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
2e9a0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
2e9b0 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  "..** ^The sqlit
2e9c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e9d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  n() interface re
2e9e0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
2e9f0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2ea00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
2ea10 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
2ea20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2ea30 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
2ea40 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
2ea50 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
2ea60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  he.** [sqlite3_l
2ea70 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2ea80 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2ea90 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66   attempt to.** f
2eaa0 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69  ill *pzErrMsg wi
2eab0 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  th error message
2eac0 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
2ead0 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e  memory.** obtain
2eae0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2eaf0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20  _malloc()]. The 
2eb00 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2eb10 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20  .** should free 
2eb20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
2eb30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2eb40 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2eb50 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2eb60 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
2eb70 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2eb80 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2eb90 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2eba0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
2ebb0 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72  is API,.** other
2ebc0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69  wise an error wi
2ebd0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
2ebe0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2ebf0 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
2ec00 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  on() SQL functio
2ec10 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  n]..*/.int sqlit
2ec20 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2ec30 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2ec40 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
2ec50 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
2ec60 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
2ec70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
2ec80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ec90 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
2eca0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
2ecb0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
2ecc0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
2ecd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2ece0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
2ecf0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
2ed00 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
2ed10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
2ed20 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
2ed30 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
2ed40 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
2ed50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2ed60 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2ed70 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
2ed80 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
2ed90 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70  ^So as not to op
2eda0 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65  en security hole
2edb0 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69  s in older appli
2edc0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  cations that are
2edd0 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74  .** unprepared t
2ede0 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65  o deal with exte
2edf0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61  nsion loading, a
2ee00 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66  nd as a means of
2ee10 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78   disabling.** ex
2ee20 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ee30 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
2ee40 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
2ee50 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  L, the following
2ee60 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69   API.** is provi
2ee70 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20  ded to turn the 
2ee80 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
2ee90 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61  tension()] mecha
2eea0 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  nism on and off.
2eeb0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
2eec0 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66  n loading is off
2eed0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65   by default. See
2eee0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
2eef0 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  * ^Call the sqli
2ef00 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2ef10 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
2ef20 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
2ef30 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74  1.** to turn ext
2ef40 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f  ension loading o
2ef50 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  n and call it wi
2ef60 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
2ef70 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f  urn.** it back o
2ef80 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74  ff again..*/.int
2ef90 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2efa0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
2efb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
2efc0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
2efd0 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74  API3REF: Automat
2efe0 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
2eff0 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  xtensions.**.** 
2f000 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65  ^This API can be
2f010 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
2f020 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
2f030 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
2f040 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
2f050 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
2f060 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
2f070 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
2f080 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
2f090 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2f0a0 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20  ections]..**.** 
2f0b0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  ^(This routine s
2f0c0 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
2f0d0 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
2f0e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
2f0f0 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
2f100 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2f110 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2f120 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f  c()].  That memo
2f130 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63  ry.** is dealloc
2f140 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2f150 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
2f160 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  nsion()].)^.**.*
2f170 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
2f180 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78   registers an ex
2f190 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
2f1a0 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61  int that is.** a
2f1b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2f1c0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2f1d0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
2f1e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20  nnection].** is 
2f1f0 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  opened using [sq
2f200 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2f210 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2f220 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2f230 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
2f240 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74 65   ^Duplicate exte
2f250 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
2f260 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
2f270 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d  his routine.** m
2f280 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
2f290 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
2f2a0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
2f2b0 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63  s..** ^Automatic
2f2c0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
2f2d0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
2f2e0 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eads..*/.int sql
2f2f0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
2f300 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
2f310 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
2f320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f330 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
2f340 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2f350 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ng.**.** ^(This 
2f360 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2f370 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
2f380 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
2f390 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69  matic.** extensi
2f3a0 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74  ons. It undoes t
2f3b0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
2f3c0 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74   prior.** [sqlit
2f3d0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2f3e0 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a  n()] calls.)^.**
2f3f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
2f400 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
2f410 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2f420 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
2f430 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2f440 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
2f450 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
2f460 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
2f470 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
2f480 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
2f490 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
2f4a0 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65  ******.**.** The
2f4b0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
2f4c0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2f4d0 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
2f4e0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
2f4f0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
2f500 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
2f510 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
2f520 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
2f530 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
2f540 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
2f550 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
2f560 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
2f570 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
2f580 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
2f590 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2f5a0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
2f5b0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
2f5c0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
2f5d0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
2f5e0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
2f5f0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
2f600 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
2f610 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
2f620 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
2f630 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
2f640 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
2f650 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2f660 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
2f670 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
2f680 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2f690 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
2f6a0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
2f6b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2f6c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
2f6d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2f6e0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
2f6f0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
2f700 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
2f710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f720 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
2f730 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2f740 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
2f750 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
2f760 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58  le module}.** EX
2f770 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2f780 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
2f790 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
2f7a0 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
2f7b0 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
2f7c0 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
2f7d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f7e0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
2f7f0 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
2f800 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
2f810 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
2f820 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2f830 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
2f840 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2f850 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
2f860 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
2f870 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
2f880 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
2f890 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
2f8a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2f8b0 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
2f8c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2f8d0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
2f8e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2f8f0 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
2f900 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
2f910 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
2f920 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
2f930 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
2f940 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
2f950 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
2f960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f970 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
2f980 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
2f990 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
2f9a0 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
2f9b0 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
2f9c0 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
2f9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f9e0 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
2f9f0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
2fa00 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
2fa10 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
2fa20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
2fa30 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
2fa40 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
2fa50 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
2fa60 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
2fa70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2fa80 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
2fa90 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
2faa0 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
2fab0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
2fac0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2fad0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
2fae0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
2faf0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
2fb00 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
2fb10 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
2fb20 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
2fb30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fb40 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
2fb50 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
2fb60 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
2fb70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fb80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fb90 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
2fba0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2fbb0 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
2fbc0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2fbd0 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
2fbe0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
2fbf0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
2fc00 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
2fc10 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2fc20 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
2fc30 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2fc40 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
2fc50 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
2fc60 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2fc70 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
2fc80 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
2fc90 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
2fca0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2fcb0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2fcc0 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
2fcd0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2fce0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
2fcf0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fd00 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
2fd10 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
2fd20 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
2fd30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2fd40 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2fd50 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
2fd60 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
2fd70 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
2fd80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2fd90 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2fda0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
2fdb0 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
2fdc0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2fdd0 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
2fde0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2fdf0 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
2fe00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fe10 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fe20 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
2fe30 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2fe40 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
2fe50 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
2fe60 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
2fe70 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
2fe80 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
2fe90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fea0 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
2feb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fec0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fed0 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2fef0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
2ff00 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
2ff10 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
2ff20 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
2ff30 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
2ff40 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2ff50 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
2ff60 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
2ff70 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
2ff80 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20  3_index_info.** 
2ff90 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2ffa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
2ffb0 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
2ffc0 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
2ffd0 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
2ffe0 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
2fff0 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
30000 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
30010 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
30020 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
30030 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
30040 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
30050 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
30060 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
30070 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
30080 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
30090 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
300a0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
300b0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
300c0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
300d0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
300e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
300f0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
30100 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
30110 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
30120 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
30130 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
30140 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
30150 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
30160 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
30170 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
30180 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
30190 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
301a0 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
301b0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29  onstraint[].op.)
301c0 5e 20 20 5e 54 68 65 20 69 6e 64 65 78 20 6f 66  ^  ^The index of
301d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
301e0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e  tored in.** aCon
301f0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
30200 6e 2e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e  n.  ^(aConstrain
30210 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
30220 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
30230 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
30240 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
30250 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
30260 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
30270 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
30280 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
30290 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a   cannot.)^.**.**
302a0 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20   ^The optimizer 
302b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
302c0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
302d0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
302e0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
302f0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
30300 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
30310 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
30320 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
30330 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
30340 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
30350 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
30360 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
30370 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68  possible..** ^Th
30380 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
30390 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
303a0 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
303b0 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a  terms that are.*
303c0 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68  * relevant to th
303d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
303e0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
303f0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
30400 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f  ^Information abo
30410 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
30420 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
30430 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
30440 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66  ** ^Each term of
30450 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
30460 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
30470 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30480 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
30490 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
304a0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
304b0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
304c0 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
304d0 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
304e0 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
304f0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66  to xFilter.  ^If
30500 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
30510 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
30520 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
30530 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
30540 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
30550 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
30560 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
30570 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
30580 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43  n argv.  ^(If aC
30590 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
305a0 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
305b0 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
305c0 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
305d0 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
305e0 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
305f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
30600 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
30610 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
30620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64  )^.**.** ^The id
30630 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
30640 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
30650 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
30660 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c  nto the.** [xFil
30670 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20  ter] method..** 
30680 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  ^[sqlite3_free()
30690 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ] is used to fre
306a0 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20  e idxPtr if and 
306b0 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64  only iff.** need
306c0 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20  ToFreeIdxPtr is 
306d0 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  true..**.** ^The
306e0 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
306f0 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70   means that outp
30700 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72  ut from [xFilter
30710 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f  ]/[xNext] will o
30720 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63  ccur in.** the c
30730 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20  orrect order to 
30740 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45  satisfy the ORDE
30750 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74  R BY clause so t
30760 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a  hat no separate.
30770 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20  ** sorting step 
30780 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
30790 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65  ** ^The estimate
307a0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
307b0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
307c0 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
307d0 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
307e0 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
307f0 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
30800 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
30810 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
30820 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
30830 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
30840 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
30850 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
30860 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
30870 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
30880 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
30890 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
308a0 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
308b0 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72  */.  int nConstr
308c0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
308d0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
308e0 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
308f0 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  int */.  struct 
30900 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
30910 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20  nstraint {.     
30920 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
30930 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
30940 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64  umn on left-hand
30950 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61   side of constra
30960 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  int */.     unsi
30970 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20  gned char op;   
30980 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61        /* Constra
30990 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a  int operator */.
309a0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
309b0 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f  ar usable;     /
309c0 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63  * True if this c
309d0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61  onstraint is usa
309e0 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20  ble */.     int 
309f0 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20  iTermOffset;    
30a00 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
30a10 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74  ternally - xBest
30a20 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e  Index should ign
30a30 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  ore */.  } *aCon
30a40 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
30a50 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20      /* Table of 
30a60 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
30a70 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e  straints */.  in
30a80 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
30a90 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
30aa0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74  er of terms in t
30ab0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30ac0 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  se */.  struct s
30ad0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
30ae0 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20  erby {.     int 
30af0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
30b00 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
30b10 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75  number */.     u
30b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73  nsigned char des
30b30 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  c;       /* True
30b40 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73   for DESC.  Fals
30b50 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20  e for ASC. */.  
30b60 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20  } *aOrderBy;    
30b70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68             /* Th
30b80 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30b90 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74  e */.  /* Output
30ba0 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  s */.  struct sq
30bb0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
30bc0 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20  traint_usage {. 
30bd0 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78     int argvIndex
30be0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69  ;           /* i
30bf0 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74  f >0, constraint
30c00 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76   is part of argv
30c10 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20   to xFilter */. 
30c20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
30c30 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44   omit;      /* D
30c40 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73  o not code a tes
30c50 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74  t for this const
30c60 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43  raint */.  } *aC
30c70 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
30c80 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
30c90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30ca0 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
30cb0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
30cc0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
30cd0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
30ce0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
30cf0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
30d00 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
30d10 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
30d20 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
30d30 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
30d40 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
30d50 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
30d60 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
30d70 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
30d80 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
30d90 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
30da0 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
30db0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
30dc0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
30dd0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
30de0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
30df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
30e00 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
30e10 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
30e20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
30e30 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
30e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
30e50 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
30e60 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
30e70 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
30e80 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
30e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30ea0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30eb0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
30ec0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30ed0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
30ee0 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  64../*.** CAPI3R
30ef0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56  EF: Register A V
30f00 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70  irtual Table Imp
30f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 45  lementation.** E
30f20 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
30f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
30f40 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 65  s are used to re
30f50 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69  gister a new [vi
30f60 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30f70 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f  le] name..** ^Mo
30f80 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20  dule names must 
30f90 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65  be registered be
30fa0 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67  fore.** creating
30fb0 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20   a new [virtual 
30fc0 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65  table] using the
30fd0 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f   module and befo
30fe0 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72  re using a.** pr
30ff0 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75  eexisting [virtu
31000 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68  al table] for th
31010 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
31020 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65  ^The module name
31030 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f   is registered o
31040 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
31050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
31060 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
31070 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
31080 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74    ^The name of t
31090 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76  he module is giv
310a0 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65  en by the .** se
310b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
310c0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
310d0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
310e0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70  er to.** the imp
310f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
31100 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
31110 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68  e module].   ^Th
31120 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61  e fourth.** para
31130 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
31140 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74  trary client dat
31150 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
31160 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
31170 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43  .** into the [xC
31180 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
31190 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
311a0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
311b0 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65  le module.** whe
311c0 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20  n a new virtual 
311d0 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e  table is be bein
311e0 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69  g created or rei
311f0 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a  nitialized..**.*
31200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
31210 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
31220 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20  ) interface has 
31230 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  a fifth paramete
31240 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
31250 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
31260 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
31270 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53  pClientData.  ^S
31280 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e  QLite will.** in
31290 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
312a0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66  tor function (if
312b0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29   it is not NULL)
312c0 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   when SQLite.** 
312d0 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20  no longer needs 
312e0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20  the pClientData 
312f0 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 73  pointer.  ^The s
31300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
31310 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  dule().** interf
31320 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
31330 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
31340 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
31350 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64  with a NULL.** d
31360 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51  estructor..*/.SQ
31370 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
31380 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
31390 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
313a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
313b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
313c0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
313d0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
313e0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
313f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
31400 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
31410 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
31420 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
31430 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
31440 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
31450 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
31460 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
31470 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
31480 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
31490 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
314a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
314b0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
314c0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
314d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
314e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
314f0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
31500 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
31510 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
31520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
31530 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
31540 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
31550 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
31560 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
31570 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
31580 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
31590 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
315a0 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ata,         /* 
315b0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
315c0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
315d0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
315e0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
315f0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
31600 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
31610 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
31620 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
31630 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a  ble Instance Obj
31640 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
31650 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a   sqlite3_vtab.**
31660 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
31670 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
31680 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
31690 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
316a0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a  uses a subclass.
316b0 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ** of this objec
316c0 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  t to describe a 
316d0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
316e0 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76  nce.** of the [v
316f0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20  irtual table].  
31700 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
31710 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65  ll.** be tailore
31720 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
31730 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
31740 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
31750 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72  tion..** The pur
31760 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70  pose of this sup
31770 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65  erclass is to de
31780 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65  fine certain fie
31790 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  lds that are.** 
317a0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f  common to all mo
317b0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
317c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72  ions..**.** ^Vir
317d0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68  tual tables meth
317e0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65  ods can set an e
317f0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20  rror message by 
31800 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73  assigning a.** s
31810 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
31820 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
31830 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d  intf()] to zErrM
31840 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
31850 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
31860 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
31870 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
31880 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
31890 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
318a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
318b0 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
318c0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
318d0 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f   ^After the erro
318e0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20  r message.** is 
318f0 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20  delivered up to 
31900 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69  the client appli
31910 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69  cation, the stri
31920 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ng will be autom
31930 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65  atically.** free
31940 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65  d by sqlite3_fre
31950 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72  e() and the zErr
31960 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62  Msg field will b
31970 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72  e zeroed..*/.str
31980 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
31990 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
319a0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
319b0 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
319c0 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
319d0 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
319e0 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
319f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31a00 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44  * NO LONGER USED
31a10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72   */.  char *zErr
31a20 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20  Msg;            
31a30 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
31a40 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69  essage from sqli
31a50 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f  te3_mprintf() */
31a60 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
31a70 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
31a80 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
31a90 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
31aa0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
31ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31ac0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75  Virtual Table Cu
31ad0 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  rsor Object.** K
31ae0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
31af0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69  _vtab_cursor {vi
31b00 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73  rtual table curs
31b10 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  or}.** EXPERIMEN
31b20 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  TAL.**.** Every 
31b30 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31b40 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
31b50 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
31b60 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
31b70 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
31b80 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20  ure to describe 
31b90 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69  cursors that poi
31ba0 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  nt into the.** [
31bb0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61  virtual table] a
31bc0 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74  nd are used.** t
31bd0 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74  o loop through t
31be0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
31bf0 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63  .  Cursors are c
31c00 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
31c10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  .** [sqlite3_mod
31c20 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65  ule.xOpen | xOpe
31c30 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
31c40 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20   module and are 
31c50 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20  destroyed.** by 
31c60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  the [sqlite3_mod
31c70 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c  ule.xClose | xCl
31c80 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75  ose] method.  Cu
31c90 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a  rsors are used.*
31ca0 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65  * by the [xFilte
31cb0 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45  r], [xNext], [xE
31cc0 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20  of], [xColumn], 
31cd0 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74  and [xRowid] met
31ce0 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d  hods.** of the m
31cf0 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64  odule.  Each mod
31d00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
31d10 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a  on will define.*
31d20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
31d30 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74   a cursor struct
31d40 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20  ure to suit its 
31d50 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  own needs..**.**
31d60 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   This superclass
31d70 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72   exists in order
31d80 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64   to define field
31d90 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20  s of the cursor 
31da0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d  that.** are comm
31db0 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d  on to all implem
31dc0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74  entations..*/.st
31dd0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
31de0 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c  b_cursor {.  sql
31df0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
31e00 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61  ;      /* Virtua
31e10 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20  l table of this 
31e20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56  cursor */.  /* V
31e30 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
31e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
31e50 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
31e60 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
31e70 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
31e80 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
31e90 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41   The Schema Of A
31ea0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
31eb0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
31ec0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61  *.** ^The [xCrea
31ed0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
31ee0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a  t] methods of a.
31ef0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
31f00 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74  e module] call t
31f10 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  his interface.**
31f20 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20   to declare the 
31f30 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65  format (the name
31f40 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
31f50 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20  of the columns) 
31f60 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61  of.** the virtua
31f70 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d  l tables they im
31f80 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  plement..*/.SQLI
31f90 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
31fa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
31fb0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
31fc0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
31fd0 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  SQL);../*.** CAP
31fe0 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
31ff0 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
32000 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
32010 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
32020 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74  *.** ^(Virtual t
32030 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
32040 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
32050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
32060 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
32070 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75  ing the [xFindFu
32080 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f  nction] method o
32090 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
320a0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a  able module].  .
320b0 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  ** But global ve
320c0 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
320d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
320e0 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
320f0 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
32100 64 2e 29 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  d.).**.** ^(This
32110 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
32120 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
32130 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
32140 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
32150 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
32160 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
32170 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
32180 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
32190 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
321a0 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
321b0 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
321c0 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e  on is created.)^
321d0 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74    ^The implement
321e0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
321f0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
32200 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
32210 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
32220 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
32230 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
32240 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
32250 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
32260 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
32270 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
32280 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
32290 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
322a0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
322b0 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74   by a [virtual t
322c0 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  able]..*/.SQLITE
322d0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
322e0 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
322f0 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
32300 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
32310 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
32320 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
32330 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
32340 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
32350 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
32360 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
32370 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
32380 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
32390 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
323a0 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
323b0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
323c0 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
323d0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
323e0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
323f0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
32400 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
32410 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
32420 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
32430 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
32440 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
32450 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
32460 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
32470 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
32480 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
32490 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
324a0 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
324b0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
324c0 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
324d0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a  comment..**.****
324e0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
324f0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
32500 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
32510 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
32520 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.*/../*.** CAPI
32530 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54  3REF: A Handle T
32540 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  o An Open BLOB.*
32550 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f  * KEYWORDS: {BLO
32560 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20  B handle} {BLOB 
32570 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41  handles}.**.** A
32580 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
32590 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
325a0 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
325b0 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73  B on which.** [s
325c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
325d0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
325e0 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20  LOB I/O] can be 
325f0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f  performed..** ^O
32600 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74  bjects of this t
32610 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20  ype are created 
32620 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
32630 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
32640 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
32650 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
32660 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ()]..** ^The [sq
32670 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
32680 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32690 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e  blob_write()] in
326a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20  terfaces.** can 
326b0 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  be used to read 
326c0 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73  or write small s
326d0 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68  ubsections of th
326e0 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20  e BLOB..** ^The 
326f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
32700 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
32710 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
32720 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e  e of the BLOB in
32730 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64   bytes..*/.typed
32740 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
32750 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62  3_blob sqlite3_b
32760 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lob;../*.** CAPI
32770 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f  3REF: Open A BLO
32780 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61  B For Incrementa
32790 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  l I/O.**.** ^(Th
327a0 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70  is interfaces op
327b0 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64  ens a [BLOB hand
327c0 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20  le | handle] to 
327d0 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64  the BLOB located
327e0 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c  .** in row iRow,
327f0 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c   column zColumn,
32800 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e   table zTable in
32810 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a   database zDb;.*
32820 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * in other words
32830 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20  , the same BLOB 
32840 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65  that would be se
32850 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a  lected by:.**.**
32860 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45   <pre>.**     SE
32870 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f  LECT zColumn FRO
32880 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45  M zDb.zTable WHE
32890 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f  RE [rowid] = iRo
328a0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a  w;.** </pre>)^.*
328b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61  *.** ^If the fla
328c0 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  gs parameter is 
328d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
328e0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
328f0 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e  d for read.** an
32900 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20  d write access. 
32910 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20  ^If it is zero, 
32920 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
32930 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65  ed for read acce
32940 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f  ss..** ^It is no
32950 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
32960 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
32970 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69   is part of an i
32980 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20  ndex or primary 
32990 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74  .** key for writ
329a0 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67  ing. ^If [foreig
329b0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
329c0 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20  s] are enabled, 
329d0 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f  it is .** not po
329e0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
329f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
32a00 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64  part of a [child
32a10 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e   key] for writin
32a20 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  g..**.** ^Note t
32a30 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
32a40 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65   name is not the
32a50 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63   filename that c
32a60 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64  ontains.** the d
32a70 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68  atabase but rath
32a80 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20  er the symbolic 
32a90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
32aa0 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70  base that.** app
32ab0 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41  ears after the A
32ac0 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74  S keyword when t
32ad0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63  he database is c
32ae0 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b  onnected using [
32af0 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72  ATTACH]..** ^For
32b00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
32b10 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74  se file, the dat
32b20 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d  abase name is "m
32b30 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45  ain"..** ^For TE
32b40 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64  MP tables, the d
32b50 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
32b60 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28  "temp"..**.** ^(
32b70 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
32b80 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
32b90 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
32ba0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73  [BLOB handle] is
32bb0 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a   written.** to *
32bc0 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73  ppBlob. Otherwis
32bd0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
32be0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
32bf0 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74  d *ppBlob is set
32c00 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c  .** to be a null
32c10 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e   pointer.)^.** ^
32c20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65  This function se
32c30 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ts the [database
32c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72   connection] err
32c50 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
32c60 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c  age.** accessibl
32c70 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
32c80 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73  rrcode()] and [s
32c90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
32ca0 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20   and related.** 
32cb0 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65  functions. ^Note
32cc0 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f   that the *ppBlo
32cd0 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c  b variable is al
32ce0 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64  ways initialized
32cf0 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61   in a.** way tha
32d00 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20  t makes it safe 
32d10 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  to invoke [sqlit
32d20 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
32d30 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72   on *ppBlob.** r
32d40 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
32d50 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
32d60 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ure of this rout
32d70 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ine..**.** ^(If 
32d80 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42  the row that a B
32d90 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74  LOB handle point
32da0 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64  s to is modified
32db0 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54   by an.** [UPDAT
32dc0 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72  E], [DELETE], or
32dd0 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54   by [ON CONFLICT
32de0 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a  ] side-effects.*
32df0 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  * then the BLOB 
32e00 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64  handle is marked
32e10 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a   as "expired"..*
32e20 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69  * This is true i
32e30 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20  f any column of 
32e40 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67  the row is chang
32e50 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d  ed, even a colum
32e60 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  n.** other than 
32e70 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42  the one the BLOB
32e80 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20   handle is open 
32e90 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  on.)^.** ^Calls 
32ea0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
32eb0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
32ec0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
32ed0 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70  ()] for.** a exp
32ee0 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65  ired BLOB handle
32ef0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65   fail with an re
32f00 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
32f10 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20  LITE_ABORT]..** 
32f20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65  ^(Changes writte
32f30 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72  n into a BLOB pr
32f40 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ior to the BLOB 
32f50 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74  expiring are not
32f60 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
32f70 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f  by the expiratio
32f80 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20  n of the BLOB.  
32f90 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c  Such changes wil
32fa0 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  l eventually.** 
32fb0 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72  commit if the tr
32fc0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e  ansaction contin
32fd0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
32fe0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20  n.)^.**.** ^Use 
32ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
33000 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
33010 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  face to determin
33020 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  e the size of.**
33030 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62   the opened blob
33040 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20  .  ^The size of 
33050 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62  a blob may not b
33060 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69  e changed by thi
33070 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  s.** interface. 
33080 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45   Use the [UPDATE
33090 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f  ] SQL command to
330a0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
330b0 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a   of a.** blob..*
330c0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
330d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
330e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
330f0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33100 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
33110 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d  * and the built-
33120 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51  in [zeroblob] SQ
33130 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62  L function can b
33140 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72  e used, if desir
33150 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65  ed,.** to create
33160 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d   an empty, zero-
33170 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77  filled blob in w
33180 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20  hich to read or 
33190 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74  write using.** t
331a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
331b0 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20  *.** To avoid a 
331c0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65  resource leak, e
331d0 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  very open [BLOB 
331e0 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65  handle] should e
331f0 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20  ventually.** be 
33200 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61  released by a ca
33210 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
33220 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f  lob_close()]..*/
33230 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
33240 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
33250 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
33260 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
33270 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
33280 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
33290 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
332a0 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
332b0 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
332c0 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
332d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
332e0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
332f0 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c  Handle.**.** ^Cl
33300 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  oses an open [BL
33310 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  OB handle]..**.*
33320 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  * ^Closing a BLO
33330 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
33340 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
33350 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
33360 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
33370 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
33380 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
33390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
333a0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
333b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
333c0 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
333d0 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61   mode]..** ^If a
333e0 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d  ny writes were m
333f0 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c  ade to the BLOB,
33400 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68   they might be h
33410 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20  eld in cache.** 
33420 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20  until the close 
33430 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65  operation if the
33440 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a  y will fit..**.*
33450 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20  * ^(Closing the 
33460 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65  BLOB often force
33470 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a  s the changes.**
33480 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64   out to disk and
33490 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65   so if any I/O e
334a0 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65  rrors occur, the
334b0 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63  y will likely oc
334c0 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69  cur.** at the ti
334d0 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42  me when the BLOB
334e0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79   is closed.  Any
334f0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
33500 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
33510 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
33520 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
33530 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a  return value.)^.
33540 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42  **.** ^(The BLOB
33550 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e   is closed uncon
33560 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65  ditionally.  Eve
33570 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e  n if this routin
33580 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20  e returns.** an 
33590 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20  error code, the 
335a0 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c  BLOB is still cl
335b0 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  osed.)^.**.** ^C
335c0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
335d0 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20  ine with a null 
335e0 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73  pointer (such as
335f0 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e   would be return
33600 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65  ed.** by a faile
33610 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
33620 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
33630 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
33640 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  o-op..*/.int sql
33650 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33660 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
33670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33680 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a  : Return The Siz
33690 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
336a0 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73  B.**.** ^Returns
336b0 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
336c0 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61  es of the BLOB a
336d0 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
336e0 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  e .** successful
336f0 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20  ly opened [BLOB 
33700 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f  handle] in its o
33710 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  nly argument.  ^
33720 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  The.** increment
33730 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74  al blob I/O rout
33740 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65  ines can only re
33750 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e  ad or overwritin
33760 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c  g existing.** bl
33770 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79  ob content; they
33780 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
33790 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
337a0 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  b..**.** This ro
337b0 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
337c0 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
337d0 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
337e0 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
337f0 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
33800 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
33810 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
33820 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
33830 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
33840 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
33850 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
33860 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
33870 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
33880 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
33890 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
338a0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
338b0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
338c0 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  avior..*/.int sq
338d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
338e0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
338f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33900 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  F: Read Data Fro
33910 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
33920 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54  ntally.**.** ^(T
33930 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
33940 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
33950 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b  a from an open [
33960 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74  BLOB handle] int
33970 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  o a.** caller-su
33980 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
33990 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
339a0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
339b0 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20  uffer Z.** from 
339c0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
339d0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
339e0 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a  t iOffset.)^.**.
339f0 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
33a00 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
33a10 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
33a20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
33a30 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
33a40 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
33a50 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
33a60 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f  s read.  ^If N o
33a70 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20  r iOffset is.** 
33a80 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
33a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
33aa0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
33ab0 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a  o data is read..
33ac0 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20  ** ^The size of 
33ad0 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65  the blob (and he
33ae0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  nce the maximum 
33af0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73  value of N+iOffs
33b00 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  et).** can be de
33b10 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
33b20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
33b30 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
33b40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ace..**.** ^An a
33b50 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66  ttempt to read f
33b60 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b  rom an expired [
33b70 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
33b80 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
33b90 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
33ba0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
33bb0 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
33bc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33bd0 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
33be0 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77  TE_OK..** Otherw
33bf0 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  ise, an [error c
33c00 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65  ode] or an [exte
33c10 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
33c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
33c30 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
33c40 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
33c50 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
33c60 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
33c70 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
33c80 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
33c90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33ca0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
33cb0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
33cc0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
33cd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
33ce0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
33cf0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
33d00 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
33d10 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
33d20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
33d30 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
33d40 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
33d50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
33d60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
33d70 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69  b_write()]..*/.i
33d80 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33d90 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f  read(sqlite3_blo
33da0 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e  b *, void *Z, in
33db0 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t N, int iOffset
33dc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33dd0 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49  EF: Write Data I
33de0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
33df0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e  mentally.**.** ^
33e00 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
33e10 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
33e20 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
33e30 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
33e40 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  rom a.** caller-
33e50 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
33e60 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74   ^N bytes of dat
33e70 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f  a are copied fro
33e80 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a  m the buffer Z.*
33e90 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20  * into the open 
33ea0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61  BLOB, starting a
33eb0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
33ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33ed0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61  [BLOB handle] pa
33ee0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
33ef0 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e  t argument was n
33f00 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a  ot opened for.**
33f10 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
33f20 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
33f30 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
33f40 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29  pen()] was zero)
33f50 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  ,.** this functi
33f60 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
33f70 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a  TE_READONLY]..**
33f80 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
33f90 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
33fa0 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
33fb0 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
33fc0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
33fd0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
33fe0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
33ff0 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
34000 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20  ..** ^If offset 
34010 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
34020 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
34030 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
34040 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
34050 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
34060 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
34070 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49   is written.  ^I
34080 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
34090 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45  han zero [SQLITE
340a0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
340b0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
340c0 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54  is written..** T
340d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
340e0 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74  LOB (and hence t
340f0 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65  he maximum value
34100 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a   of N+iOffset).*
34110 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
34120 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ned using the [s
34130 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34140 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  s()] interface..
34150 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70  **.** ^An attemp
34160 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e  t to write to an
34170 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
34180 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
34190 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
341a0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
341b0 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74  ORT].  ^Writes t
341c0 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20  o the BLOB that 
341d0 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f  occurred.** befo
341e0 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e  re the [BLOB han
341f0 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65  dle] expired are
34200 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b   not rolled back
34210 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72   by the.** expir
34220 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e  ation of the han
34230 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  dle, though of c
34240 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e  ourse those chan
34250 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76  ges might.** hav
34260 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74  e been overwritt
34270 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  en by the statem
34280 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64  ent that expired
34290 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
342a0 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20  .** or by other 
342b0 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74  independent stat
342c0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ements..**.** ^(
342d0 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
342e0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
342f0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
34300 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  OK..** Otherwise
34310 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64  , an  [error cod
34320 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
34330 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
34340 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
34350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34360 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
34370 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
34380 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
34390 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
343a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
343b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
343c0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
343d0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
343e0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
343f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34400 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
34410 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
34420 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
34430 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
34440 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
34450 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
34460 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
34470 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34480 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
34490 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  read()]..*/.int 
344a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
344b0 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  te(sqlite3_blob 
344c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  *, const void *z
344d0 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
344e0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
344f0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
34500 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65  File System Obje
34510 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  cts.**.** A virt
34520 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
34530 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
34540 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
34550 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
34560 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
34570 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
34580 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
34590 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
345a0 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
345b0 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
345c0 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
345d0 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
345e0 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
345f0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
34600 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
34610 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
34620 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
34630 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
34640 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
34650 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
34660 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
34670 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66   ^The sqlite3_vf
34680 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61  s_find() interfa
34690 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
346a0 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69  nter to a VFS gi
346b0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a  ven its name..**
346c0 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65   ^Names are case
346d0 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e   sensitive..** ^
346e0 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74  Names are zero-t
346f0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
34700 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20  strings..** ^If 
34710 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
34720 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  h, a NULL pointe
34730 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34740 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  * ^If zVfsName i
34750 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
34760 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
34770 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
34780 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65  New VFSes are re
34790 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71  gistered with sq
347a0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
347b0 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e  er()..** ^Each n
347c0 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74  ew VFS becomes t
347d0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
347e0 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  f the makeDflt f
347f0 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e  lag is set..** ^
34800 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
34810 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
34820 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
34830 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
34840 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69   ^To make an exi
34850 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74  sting VFS into t
34860 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20  he default VFS, 
34870 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69  register it agai
34880 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61  n.** with the ma
34890 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e  keDflt flag set.
348a0 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65    If two differe
348b0 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68  nt VFSes with th
348c0 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61  e.** same name a
348d0 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74  re registered, t
348e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
348f0 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a  ndefined.  If a.
34900 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74  ** VFS is regist
34910 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65  ered with a name
34920 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72   that is NULL or
34930 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
34940 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
34950 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
34960 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65  ned..**.** ^Unre
34970 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74  gister a VFS wit
34980 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  h the sqlite3_vf
34990 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69  s_unregister() i
349a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49  nterface..** ^(I
349b0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
349c0 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
349d0 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
349e0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
349f0 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
34a00 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
34a10 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
34a20 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74  rary.)^.*/.sqlit
34a30 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f  e3_vfs *sqlite3_
34a40 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63  vfs_find(const c
34a50 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a  har *zVfsName);.
34a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
34a70 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
34a80 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44  _vfs*, int makeD
34a90 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  flt);.int sqlite
34aa0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
34ab0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
34ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34ad0 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54   Mutexes.**.** T
34ae0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
34af0 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
34b00 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
34b10 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
34b20 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72  . Though they ar
34b30 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
34b40 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
34b50 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
34b60 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
34b70 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
34b80 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
34b90 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34ba0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
34bb0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
34bc0 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
34bd0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
34be0 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73  tions.** of thes
34bf0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
34c00 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
34c10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34c20 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
34c30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
34c40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
34c50 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ^(The following.
34c60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34c70 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
34c80 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63   in the SQLite c
34c90 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ore:.**.** <ul>.
34ca0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
34cb0 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c  _MUTEX_OS2.** <l
34cc0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
34cd0 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69  X_PTHREAD.** <li
34ce0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
34cf0 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _W32.** <li>   S
34d00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
34d10 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
34d20 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  * ^The SQLITE_MU
34d30 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
34d40 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
34d50 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20   of routines.** 
34d60 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
34d70 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
34d80 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
34d90 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e   use in.** a sin
34da0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
34db0 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20  lication.  ^The 
34dc0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
34dd0 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
34de0 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
34df0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
34e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
34e10 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
34e20 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
34e30 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
34e40 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ndows..**.** ^(I
34e50 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
34e60 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
34e70 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
34e80 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
34e90 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
34ea0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
34eb0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
34ec0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
34ed0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34ee0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
34ef0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
34f00 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65  In this case the
34f10 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
34f20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75  must supply a cu
34f30 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65  stom mutex imple
34f40 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20  mentation using 
34f50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
34f60 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
34f70 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ion of the sqlit
34f80 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63  e3_config() func
34f90 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63  tion.** before c
34fa0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69  alling sqlite3_i
34fb0 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61  nitialize() or a
34fc0 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20  ny other public 
34fd0 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63  sqlite3_.** func
34fe0 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20  tion that calls 
34ff0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
35000 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ze().)^.**.** ^T
35010 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
35020 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
35030 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
35040 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
35050 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35060 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65  to it. ^If it re
35070 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
35080 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
35090 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
350a0 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  be allocated.  ^
350b0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75  SQLite.** will u
350c0 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20  nwind its stack 
350d0 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72  and return an er
350e0 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75  ror.  ^(The argu
350f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
35100 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
35110 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
35120 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
35130 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ts:.**.** <ul>.*
35140 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35150 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69  UTEX_FAST.** <li
35160 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
35170 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69  RECURSIVE.** <li
35180 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
35190 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a  STATIC_MASTER.**
351a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
351b0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a  TEX_STATIC_MEM.*
351c0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
351d0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
351e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
351f0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
35200 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  NG.** <li>  SQLI
35210 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
35220 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  LRU.** <li>  SQL
35230 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
35240 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _LRU2.** </ul>)^
35250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
35260 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  t two constants 
35270 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
35280 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  ST and SQLITE_MU
35290 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a  TEX_RECURSIVE).*
352a0 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  * cause sqlite3_
352b0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
352c0 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
352d0 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65   mutex.  ^The ne
352e0 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72  w mutex is recur
352f0 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45  sive when SQLITE
35300 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35310 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20  .** is used but 
35320 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20  not necessarily 
35330 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  so when SQLITE_M
35340 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65  UTEX_FAST is use
35350 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  d..** The mutex 
35360 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64  implementation d
35370 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
35380 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69  make a distincti
35390 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
353a0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
353b0 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  SIVE and SQLITE_
353c0 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74  MUTEX_FAST if it
353d0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
353e0 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77  t to.  ^SQLite w
353f0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74  ill only request
35400 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74   a recursive mut
35410 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77  ex in.** cases w
35420 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e  here it really n
35430 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61  eeds one.  ^If a
35440 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75   faster non-recu
35450 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69  rsive mutex.** i
35460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35470 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68   available on th
35480 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c  e host platform,
35490 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79   the mutex subsy
354a0 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65  stem.** might re
354b0 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65  turn such a mute
354c0 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  x in response to
354d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
354e0 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  ST..**.** ^The o
354f0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
35500 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
35510 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
35520 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72   (anything other
35530 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f  .** than SQLITE_
35540 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53  MUTEX_FAST and S
35550 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35560 52 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75  RSIVE) each retu
35570 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
35580 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
35590 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20  xisting mutex.  
355a0 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65  ^Six static mute
355b0 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
355c0 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
355d0 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
355e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
355f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
35600 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
35610 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
35620 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
35630 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
35640 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
35650 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
35660 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
35670 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
35680 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
35690 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
356a0 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
356b0 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
356c0 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
356d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
356e0 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  VE..**.** ^Note 
356f0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74  that if one of t
35700 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
35710 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c   parameters (SQL
35720 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
35730 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45  * or SQLITE_MUTE
35740 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20  X_RECURSIVE) is 
35750 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65  used then sqlite
35760 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a  3_mutex_alloc().
35770 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66  ** returns a dif
35780 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20  ferent mutex on 
35790 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75  every call.  ^Bu
357a0 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
357b0 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c  .** mutex types,
357c0 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20   the same mutex 
357d0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65  is returned on e
357e0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68  very call that h
357f0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  as.** the same t
35800 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  ype number..**.*
35810 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
35820 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
35830 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
35840 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
35850 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
35860 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74  c mutex.  ^SQLit
35870 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
35880 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
35890 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  .** dynamic mute
358a0 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61  x that it alloca
358b0 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69  tes.  The dynami
358c0 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e  c mutexes must n
358d0 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20  ot be in.** use 
358e0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
358f0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
35900 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
35910 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
35920 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
35930 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
35940 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e  vior.  ^SQLite n
35950 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
35960 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
35970 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ex..**.** ^The s
35980 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
35990 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  er() and sqlite3
359a0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75  _mutex_try() rou
359b0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a  tines attempt.**
359c0 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65   to enter a mute
359d0 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20  x.  ^If another 
359e0 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64  thread is alread
359f0 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74  y within the mut
35a00 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ex,.** sqlite3_m
35a10 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c  utex_enter() wil
35a20 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69  l block and sqli
35a30 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
35a40 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53  will return.** S
35a50 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68  QLITE_BUSY.  ^Th
35a60 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
35a70 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
35a80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
35a90 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
35aa0 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e  essful entry.  ^
35ab0 28 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64  (Mutexes created
35ac0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
35ad0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35ae0 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20   can be entered 
35af0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62  multiple times b
35b00 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
35b10 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61  d..** In such ca
35b20 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
35b30 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
35b40 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
35b50 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
35b60 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
35b70 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20  ** can enter.)^ 
35b80 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74   ^(If the same t
35b90 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
35ba0 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a  nter any other.*
35bb0 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20  * kind of mutex 
35bc0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
35bd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
35be0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51  undefined..** SQ
35bf0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
35c00 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20  exhibit.** such 
35c10 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20  behavior in its 
35c20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78  own use of mutex
35c30 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f  es.)^.**.** ^(So
35c40 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20  me systems (for 
35c50 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73  example, Windows
35c60 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70   95) do not supp
35c70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ort the operatio
35c80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64  n.** implemented
35c90 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   by sqlite3_mute
35ca0 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f  x_try().  On tho
35cb0 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69  se systems, sqli
35cc0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a  te3_mutex_try().
35cd0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  ** will always r
35ce0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53  eturn SQLITE_BUS
35cf0 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  Y.  The SQLite c
35d00 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73  ore only ever us
35d10 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  es.** sqlite3_mu
35d20 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20  tex_try() as an 
35d30 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20  optimization so 
35d40 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62  this is acceptab
35d50 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a  le behavior.)^.*
35d60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35d70 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
35d80 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
35d90 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
35da0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
35db0 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
35dc0 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65   thread.   ^(The
35dd0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
35de0 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65  undefined if the
35df0 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75   mutex is not cu
35e00 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
35e10 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e  by the.** callin
35e20 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e  g thread or is n
35e30 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c  ot currently all
35e40 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20  ocated.  SQLite 
35e50 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f  will.** never do
35e60 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a   either.)^.**.**
35e70 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
35e80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
35e90 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69  ex_enter(), sqli
35ea0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c  te3_mutex_try(),
35eb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   or.** sqlite3_m
35ec0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20  utex_leave() is 
35ed0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
35ee0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72  then all three r
35ef0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76  outines.** behav
35f00 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  e as no-ops..**.
35f10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
35f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
35f30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35f40 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
35f50 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
35f60 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
35f70 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
35f80 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
35f90 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
35fa0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
35fb0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35fc0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
35fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
35fe0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
35ff0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
36000 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
36010 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
36020 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36030 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64  EF: Mutex Method
36040 73 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45  s Object.** EXPE
36050 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
36060 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
36070 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66  is structure def
36080 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76  ines the low-lev
36090 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75  el routines.** u
360a0 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  sed to allocate 
360b0 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e  and use mutexes.
360c0 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20  .**.** Usually, 
360d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
360e0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
360f0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51  s provided by SQ
36100 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66  Lite are.** suff
36110 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20  icient, however 
36120 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65  the user has the
36130 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74   option of subst
36140 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d  ituting a custom
36150 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
36160 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a  on for specializ
36170 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f  ed deployments o
36180 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68  r systems for wh
36190 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  ich SQLite.** do
361a0 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  es not provide a
361b0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
361c0 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69  entation. In thi
361d0 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72  s case, the user
361e0 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20  .** creates and 
361f0 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73  populates an ins
36200 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36210 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a  ructure to pass.
36220 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
36230 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74  nfig() along wit
36240 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  h the [SQLITE_CO
36250 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
36260 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  on..** Additiona
36270 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65  lly, an instance
36280 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36290 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  re can be used a
362a0 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76  s an.** output v
362b0 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65  ariable when que
362c0 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d  rying the system
362d0 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
362e0 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
362f0 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20  entation, using 
36300 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36310 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74  IG_GETMUTEX] opt
36320 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
36330 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
36340 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
36350 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
36360 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
36370 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74  t of system init
36380 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68  ialization by th
36390 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
363a0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lize() function.
363b0 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49  .** ^The xMutexI
363c0 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63  nit routine is c
363d0 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65  alle by SQLite e
363e0 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20  xactly once for 
363f0 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76  each.** effectiv
36400 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  e call to [sqlit
36410 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
36420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ..**.** ^The xMu
36430 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65  texEnd method de
36440 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
36450 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
36460 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
36470 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e   system shutdown
36480 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36490 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74  shutdown() funct
364a0 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c  ion. The.** impl
364b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
364c0 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70  is method is exp
364d0 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65  ected to release
364e0 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67   all outstanding
364f0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62  .** resources ob
36500 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75  tained by the mu
36510 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c  tex methods impl
36520 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65  ementation, espe
36530 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20  cially.** those 
36540 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
36550 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
36560 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45  d.  ^The xMutexE
36570 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  nd().** interfac
36580 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61  e is invoked exa
36590 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
365a0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
365b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
365c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d  .**.** ^(The rem
365d0 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74  aining seven met
365e0 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20  hods defined by 
365f0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28  this structure (
36600 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20  xMutexAlloc,.** 
36610 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74  xMutexFree, xMut
36620 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54  exEnter, xMutexT
36630 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c  ry, xMutexLeave,
36640 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a   xMutexHeld and.
36650 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64  ** xMutexNotheld
36660 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  ) implement the 
36670 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66  following interf
36680 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65  aces (respective
36690 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ly):.**.** <ul>.
366a0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
366b0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
366c0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
366d0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
366e0 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e  ex_free()] </li>
366f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36700 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36710 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36720 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36730 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e  tex_try()] </li>
36740 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36750 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
36760 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36770 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36780 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  tex_held()] </li
36790 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
367a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
367b0 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  eld()] </li>.** 
367c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
367d0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
367e0 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75  e is that the pu
367f0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58  blic sqlite3_XXX
36800 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65   functions enume
36810 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73  rated.** above s
36820 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61  ilently ignore a
36830 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74  ny invocations t
36840 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20  hat pass a NULL 
36850 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a  pointer instead.
36860 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ** of a valid mu
36870 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20  tex handle. The 
36880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36890 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64  of the methods d
368a0 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  efined.** by thi
368b0 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20  s structure are 
368c0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
368d0 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65  handle this case
368e0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a  , the results.**
368f0 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55   of passing a NU
36900 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
36910 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ad of a valid mu
36920 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75  tex handle are u
36930 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65  ndefined.** (i.e
36940 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62  . it is acceptab
36950 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e  le to provide an
36960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36970 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69  that segfaults i
36980 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65  f.** it is passe
36990 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
369a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  )..**.** The xMu
369b0 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64  texInit() method
369c0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
369d0 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62  afe.  ^It must b
369e0 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a  e harmless to.**
369f0 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e   invoke xMutexIn
36a00 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d  it() mutiple tim
36a10 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
36a20 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77  me process and w
36a30 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76  ithout.** interv
36a40 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78  ening calls to x
36a50 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63  MutexEnd().  Sec
36a60 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
36a70 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78  nt calls to.** x
36a80 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
36a90 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
36aa0 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20  * ^xMutexInit() 
36ab0 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c  must not use SQL
36ac0 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ite memory alloc
36ad0 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f  ation ([sqlite3_
36ae0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64  malloc()].** and
36af0 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29   its associates)
36b00 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78  .  ^Similarly, x
36b10 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73  MutexAlloc() mus
36b20 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65  t not use SQLite
36b30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
36b40 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74  ation for a stat
36b50 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65  ic mutex.  ^Howe
36b60 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28  ver xMutexAlloc(
36b70 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65  ) may use SQLite
36b80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
36b90 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74  ation for a fast
36ba0 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75   or recursive mu
36bb0 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  tex..**.** ^SQLi
36bc0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
36bd0 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d  he xMutexEnd() m
36be0 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69  ethod when [sqli
36bf0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
36c00 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75  is.** called, bu
36c10 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72  t only if the pr
36c20 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74  ior call to xMut
36c30 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20  exInit returned 
36c40 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66  SQLITE_OK..** If
36c50 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c   xMutexInit fail
36c60 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74  s in any way, it
36c70 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20   is expected to 
36c80 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69  clean up after i
36c90 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74  tself.** prior t
36ca0 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a  o returning..*/.
36cb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
36cc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
36cd0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74  hods sqlite3_mut
36ce0 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  ex_methods;.stru
36cf0 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
36d00 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
36d10 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76   (*xMutexInit)(v
36d20 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  oid);.  int (*xM
36d30 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a  utexEnd)(void);.
36d40 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20    sqlite3_mutex 
36d50 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28  *(*xMutexAlloc)(
36d60 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  int);.  void (*x
36d70 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74  MutexFree)(sqlit
36d80 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76  e3_mutex *);.  v
36d90 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65  oid (*xMutexEnte
36da0 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  r)(sqlite3_mutex
36db0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
36dc0 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f  texTry)(sqlite3_
36dd0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
36de0 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28   (*xMutexLeave)(
36df0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
36e00 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
36e10 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75  Held)(sqlite3_mu
36e20 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  tex *);.  int (*
36e30 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73  xMutexNotheld)(s
36e40 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
36e50 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
36e60 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
36e70 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ication Routines
36e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36e90 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
36ea0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
36eb0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74  x_notheld() rout
36ec0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65  ines.** are inte
36ed0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  nded for use ins
36ee0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ide assert() sta
36ef0 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53  tements.  ^The S
36f00 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
36f10 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
36f20 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
36f30 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
36f40 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
36f50 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
36f60 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
36f70 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
36f80 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63  .  ^The SQLite c
36f90 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
36fa0 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
36fb0 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
36fc0 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
36fd0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
36fe0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
36ff0 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74  EBUG flag.  ^Ext
37000 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c  ernal mutex impl
37010 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
37020 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64  re only required
37030 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73   to provide thes
37040 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51  e routines if SQ
37050 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a  LITE_DEBUG is.**
37060 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20   defined and if 
37070 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65  NDEBUG is not de
37080 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
37090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
370a0 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
370b0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
370c0 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
370d0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
370e0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
370f0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
37100 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
37110 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  * ^The implement
37120 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71  ation is not req
37130 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
37140 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  d versions of th
37150 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ese.** routines 
37160 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f  that actually wo
37170 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65  rk. If the imple
37180 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e  mentation does n
37190 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69  ot provide worki
371a0 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  ng.** versions o
371b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
371c0 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c  , it should at l
371d0 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75  east provide stu
371e0 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a  bs that always.*
371f0 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f  * return true so
37200 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e   that one does n
37210 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20  ot get spurious 
37220 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72  assertion failur
37230 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
37240 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
37250 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
37260 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
37270 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
37280 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
37290 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73  return 1.   This
372a0 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69   seems counter-i
372b0 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a  ntuitive since.*
372c0 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75  * clearly the mu
372d0 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65  tex cannot be he
372e0 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f  ld if it does no
372f0 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68  t exist.  But th
37300 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20  e.** the reason 
37310 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e  the mutex does n
37320 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61  ot exist is beca
37330 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73  use the build is
37340 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75   not.** using mu
37350 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64  texes.  And we d
37360 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61  o not want the a
37370 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69  ssert() containi
37380 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74  ng the.** call t
37390 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
373a0 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20  held() to fail, 
373b0 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  so a non-zero re
373c0 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61  turn is.** the a
373d0 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67  ppropriate thing
373e0 20 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71   to do.  ^The sq
373f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37400 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  eld().** interfa
37410 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72  ce should also r
37420 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76  eturn 1 when giv
37430 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
37440 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44  r..*/.#ifndef ND
37450 45 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33  EBUG.int sqlite3
37460 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69  _mutex_held(sqli
37470 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
37480 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
37490 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  otheld(sqlite3_m
374a0 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a  utex*);.#endif..
374b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
374c0 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a  Mutex Types.**.*
374d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
374e0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e  utex_alloc()] in
374f0 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20  terface takes a 
37500 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
37510 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20  ** which is one 
37520 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
37530 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
37540 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61  * The set of sta
37550 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20  tic mutexes may 
37560 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20  change from one 
37570 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74  SQLite release t
37580 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
37590 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
375a0 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62  t override the b
375b0 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f  uilt-in mutex lo
375c0 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70  gic must be.** p
375d0 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d  repared to accom
375e0 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61  modate additiona
375f0 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
37600 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
37610 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20  ITE_MUTEX_FAST  
37620 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
37630 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37640 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  X_RECURSIVE     
37650 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
37660 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37670 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65  _MASTER    2.#de
37680 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37690 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20  X_STATIC_MEM    
376a0 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33     3  /* sqlite3
376b0 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65  _malloc() */.#de
376c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
376d0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20  X_STATIC_MEM2   
376e0 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45     4  /* NOT USE
376f0 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  D */.#define SQL
37700 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37710 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a  _OPEN      4  /*
37720 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65   sqlite3BtreeOpe
37730 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  n() */.#define S
37740 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37750 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20  IC_PRNG      5  
37760 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  /* sqlite3_rando
37770 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  m() */.#define S
37780 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37790 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20  IC_LRU       6  
377a0 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74  /* lru page list
377b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
377c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
377d0 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20  LRU2      7  /* 
377e0 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f  lru page list */
377f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37800 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d  : Retrieve the m
37810 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62  utex for a datab
37820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
37830 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
37840 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
37850 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69  ointer the [sqli
37860 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
37870 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61  t that .** seria
37880 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20  lizes access to 
37890 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
378a0 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20  nnection] given 
378b0 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
378c0 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72  ** when the [thr
378d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
378e0 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e  Serialized..** ^
378f0 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  If the [threadin
37900 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c  g mode] is Singl
37910 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74  e-thread or Mult
37920 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68  i-thread then th
37930 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  is.** routine re
37940 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
37950 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
37960 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f  _mutex *sqlite3_
37970 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33  db_mutex(sqlite3
37980 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37990 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43  REF: Low-Level C
379a0 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61  ontrol Of Databa
379b0 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
379c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  The [sqlite3_fil
379d0 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
379e0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64  erface makes a d
379f0 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68  irect call to th
37a00 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  e.** xFileContro
37a10 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65  l method for the
37a20 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
37a30 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73  hods] object ass
37a40 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
37a50 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
37a60 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64  abase identified
37a70 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
37a80 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a  rgument. ^The.**
37a90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
37aa0 61 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72  abase "main" for
37ab0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
37ac0 73 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72  se or "temp" for
37ad0 20 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74   the.** TEMP dat
37ae0 61 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61  abase, or the na
37af0 6d 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20  me that appears 
37b00 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79  after the AS key
37b10 77 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61  word for.** data
37b20 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61  bases that are a
37b30 64 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  dded using the [
37b40 41 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d  ATTACH] SQL comm
37b50 61 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20  and..** ^A NULL 
37b60 70 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75  pointer can be u
37b70 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  sed in place of 
37b80 22 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20  "main" to refer 
37b90 74 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64  to the.** main d
37ba0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
37bb0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
37bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37bd0 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  s to this routin
37be0 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  e.** are passed 
37bf0 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68  directly through
37c00 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61   to the second a
37c10 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  nd third paramet
37c20 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ers of.** the xF
37c30 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
37c40 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20  d.  ^The return 
37c50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
37c60 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
37c70 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
37c80 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
37c90 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
37ca0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
37cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44  nd parameter (zD
37cc0 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20  bName) does not 
37cd0 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f  match the name o
37ce0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61  f any.** open da
37cf0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
37d00 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
37d10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
37d20 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  is error.** code
37d30 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72   is not remember
37d40 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20  ed and will not 
37d50 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b  be recalled by [
37d60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
37d70 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
37d80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68  3_errmsg()].  Th
37d90 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69  e underlying xFi
37da0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
37db0 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72   might.** also r
37dc0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52  eturn SQLITE_ERR
37dd0 4f 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f  OR.  There is no
37de0 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
37df0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
37e00 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
37e10 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
37e20 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
37e30 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
37e40 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
37e50 6f 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a  ol method..**.**
37e60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
37e70 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
37e80 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  TE].*/.int sqlit
37e90 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
37ea0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
37eb0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69  char *zDbName, i
37ec0 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt op, void*);..
37ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37ee0 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63  Testing Interfac
37ef0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
37f00 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
37f10 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  l() interface is
37f20 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75   used to read ou
37f30 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74  t internal.** st
37f40 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e  ate of SQLite an
37f50 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c  d to inject faul
37f60 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66  ts into SQLite f
37f70 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75  or testing.** pu
37f80 72 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69  rposes.  ^The fi
37f90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
37fa0 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f   an operation co
37fb0 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  de that determin
37fc0 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  es.** the number
37fd0 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f  , meaning, and o
37fe0 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20  peration of all 
37ff0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
38000 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  eters..**.** Thi
38010 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
38020 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70  ot for use by ap
38030 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20  plications.  It 
38040 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a  exists solely.**
38050 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74   for verifying t
38060 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61  he correct opera
38070 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
38080 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70  te library.  Dep
38090 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77  ending.** on how
380a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
380b0 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c  ary is compiled,
380c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
380d0 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e  might not exist.
380e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
380f0 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74  ls of the operat
38100 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72  ion codes, their
38110 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70   meanings, the p
38120 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65  arameters.** the
38130 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74  y take, and what
38140 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c   they do are all
38150 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
38160 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
38170 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73  e..** Unlike mos
38180 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  t of the SQLite 
38190 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69  API, this functi
381a0 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  on is not guaran
381b0 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61  teed to.** opera
381c0 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20  te consistently 
381d0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
381e0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
381f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73  .int sqlite3_tes
38200 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70  t_control(int op
38210 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
38220 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67  API3REF: Testing
38230 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61   Interface Opera
38240 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
38250 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
38260 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f   are the valid o
38270 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61  peration code pa
38280 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a  rameters used.**
38290 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
382a0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
382b0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
382c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
382d0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74  parameters and t
382e0 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72  heir meanings ar
382f0 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
38300 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e  nge.** without n
38310 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61  otice.  These va
38320 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73  lues are for tes
38330 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e  ting purposes on
38340 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ly..** Applicati
38350 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75  ons should not u
38360 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  se any of these 
38370 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68  parameters or th
38380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65  e.** [sqlite3_te
38390 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  st_control()] in
383a0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
383b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
383c0 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20  TRL_PRNG_SAVE   
383d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
383e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
383f0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54  STCTRL_PRNG_REST
38400 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ORE             
38410 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
38420 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52  _TESTCTRL_PRNG_R
38430 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20  ESET            
38440 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
38450 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54  ITE_TESTCTRL_BIT
38460 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20  VEC_TEST        
38470 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
38480 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
38490 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20  FAULT_INSTALL   
384a0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
384b0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
384c0 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43  RL_BENIGN_MALLOC
384d0 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64  _HOOKS     10.#d
384e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
384f0 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59  TCTRL_PENDING_BY
38500 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31  TE            11
38510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38520 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20  TESTCTRL_ASSERT 
38530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38540 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
38550 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41  TE_TESTCTRL_ALWA
38560 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  YS              
38570 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
38580 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52  QLITE_TESTCTRL_R
38590 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20  ESERVE          
385a0 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a         14../*.**
385b0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74   CAPI3REF: SQLit
385c0 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73  e Runtime Status
385d0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
385e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
385f0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
38600 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69  o retrieve runti
38610 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d  me status inform
38620 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74  ation.** about t
38630 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f  he preformance o
38640 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70  f SQLite, and op
38650 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65  tionally to rese
38660 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67  t various.** hig
38670 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e  hwater marks.  ^
38680 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
38690 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
386a0 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
386b0 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65   specific parame
386c0 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20  ter to measure. 
386d0 20 5e 28 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e   ^(Recognized in
386e0 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61  teger codes.** a
386f0 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b  re of the form [
38700 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45  SQLITE_STATUS_ME
38710 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49  MORY_USED | SQLI
38720 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 29  TE_STATUS_...].)
38730 5e 0a 2a 2a 20 5e 54 68 65 20 63 75 72 72 65 6e  ^.** ^The curren
38740 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  t value of the p
38750 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75  arameter is retu
38760 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72  rned into *pCurr
38770 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 68 69 67  ent..** ^The hig
38780 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61  hest recorded va
38790 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  lue is returned 
387a0 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20  in *pHighwater. 
387b0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65   ^If the.** rese
387c0 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74  tFlag is true, t
387d0 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20  hen the highest 
387e0 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20  record value is 
387f0 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a  reset after.** *
38800 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72  pHighwater is wr
38810 69 74 74 65 6e 2e 20 20 5e 28 53 6f 6d 65 20 70  itten.  ^(Some p
38820 61 72 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74  arameters do not
38830 20 72 65 63 6f 72 64 20 74 68 65 20 68 69 67 68   record the high
38840 65 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46  est.** value.  F
38850 6f 72 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74  or those paramet
38860 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69  ers.** nothing i
38870 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  s written into *
38880 70 48 69 67 68 77 61 74 65 72 20 61 6e 64 20 74  pHighwater and t
38890 68 65 20 72 65 73 65 74 46 6c 61 67 20 69 73 20  he resetFlag is 
388a0 69 67 6e 6f 72 65 64 2e 29 5e 0a 2a 2a 20 5e 28  ignored.)^.** ^(
388b0 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 73  Other parameters
388c0 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65   record only the
388d0 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20   highwater mark 
388e0 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72  and not the curr
388f0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46  ent.** value.  F
38900 6f 72 20 7