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

Artifact 649e62a2a3f80f1cb4221faf2b5487da63208000:


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 28 54 68 65 20 73 71  ..**.** ^(The sq
10f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
10f30 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
10f40 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
10f50 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
10f60 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
10f70 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
10f80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
10f90 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77  mplete.  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 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   New SQL stateme
11080 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
11090 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
110a0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
110b0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
110c0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
110d0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
110e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
110f0 75 70 74 28 29 2e 29 5e 0a 2a 2a 20 5e 41 20 63  upt().)^.** ^A c
11100 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
11110 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
11120 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
11130 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
11140 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
11150 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
11160 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
11170 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
11180 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
11190 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
111a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
111b0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
111c0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
111d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
111e0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
111f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
11200 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
11210 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
11220 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
11230 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
11240 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11250 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
11260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
11270 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
11280 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
11290 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
112a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
112b0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
112c0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
112d0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
112e0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
112f0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
11300 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
11310 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
11320 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
11330 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
11340 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
11350 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
11360 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
11370 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
11380 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
11390 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
113a0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
113b0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
113c0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
113d0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
113e0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
113f0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
11400 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
11410 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
11420 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
11430 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
11440 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
11450 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
11460 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
11470 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
11480 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
11490 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
114a0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
114b0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
114c0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
114d0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
114e0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
114f0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
11500 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
11510 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
11520 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
11530 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
11540 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
11550 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
11560 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
11570 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
11580 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
11590 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
115a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
115b0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
115c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
115d0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
115e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
115f0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
11600 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
11610 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
11620 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
11630 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
11640 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
11650 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
11660 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
11670 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
11680 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
11690 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
116a0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
116b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
116c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
116d0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
116e0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
116f0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
11700 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11710 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
11720 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
11730 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
11740 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
11750 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
11760 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
11770 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
11780 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
11790 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
117a0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
117b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
117c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
117d0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
117e0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
117f0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
11800 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
11810 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
11820 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
11830 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
11840 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
11850 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
11860 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
11870 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
11880 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
11890 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
118a0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
118b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
118c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
118d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
118e0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
118f0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
11900 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
11910 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
11920 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
11930 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
11940 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
11950 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
11960 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
11970 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
11980 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
11990 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
119a0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
119b0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
119c0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
119d0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
119e0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
119f0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
11a00 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
11a10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
11a20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11a30 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
11a40 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
11a50 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
11a60 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
11a70 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
11a80 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
11a90 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
11aa0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
11ab0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
11ac0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
11ad0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
11ae0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
11af0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
11b00 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
11b10 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
11b20 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
11b30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11b40 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
11b50 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
11b60 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
11b70 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
11b80 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
11b90 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
11ba0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
11bb0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
11bc0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
11bd0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
11be0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
11bf0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
11c00 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
11c10 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
11c20 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
11c30 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
11c40 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
11c50 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
11c60 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
11c70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
11c80 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
11c90 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
11ca0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
11cb0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
11cc0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
11cd0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
11ce0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
11cf0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
11d00 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
11d10 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
11d20 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
11d30 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
11d40 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
11d50 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
11d60 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
11d70 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
11d80 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
11d90 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
11da0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
11db0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
11dc0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
11dd0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
11de0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
11df0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11e00 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
11e10 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
11e20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
11e30 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
11e40 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
11e50 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
11e60 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
11e70 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
11e80 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
11e90 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
11ea0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
11eb0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
11ec0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
11ed0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
11ee0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
11ef0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
11f00 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
11f10 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
11f20 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
11f30 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
11f40 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
11f50 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
11f60 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
11f70 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
11f80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
11f90 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
11fa0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
11fb0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
11fc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
11fd0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
11fe0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
11ff0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
12000 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
12010 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
12020 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
12030 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
12040 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
12050 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
12060 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
12070 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
12080 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
12090 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
120a0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
120b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
120c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
120d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
120e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
120f0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
12100 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
12110 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
12120 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
12130 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
12140 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
12150 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
12160 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
12170 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
12180 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
12190 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
121a0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
121b0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
121c0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
121d0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
121e0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
121f0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
12200 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
12210 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
12220 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
12230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
12240 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
12250 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
12260 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
12270 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
12280 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
12290 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
122a0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
122b0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
122c0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
122d0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
122e0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
122f0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
12300 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
12310 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
12320 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
12330 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
12340 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
12350 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
12360 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
12370 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
12380 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
12390 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
123a0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
123b0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
123c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
123d0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
123e0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
123f0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
12400 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
12410 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
12420 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
12430 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
12440 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
12450 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
12460 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
12470 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
12480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12490 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
124a0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
124b0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
124c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
124d0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
124e0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
124f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
12500 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
12510 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
12520 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12530 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
12540 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
12550 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
12560 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
12570 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
12580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
12590 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
125a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
125b0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
125c0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
125d0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
125e0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
125f0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
12600 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
12610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
12620 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
12630 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
12640 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
12650 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
12660 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12670 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
12680 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
12690 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
126a0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
126b0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
126c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
126d0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
126e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
126f0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
12700 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
12710 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
12720 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
12730 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
12740 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
12750 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
12760 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
12770 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
12780 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
12790 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
127a0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
127b0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
127c0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
127d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
127e0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
127f0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
12800 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
12810 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
12820 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
12830 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12840 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
12850 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
12860 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
12870 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
12880 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
12890 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
128a0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
128b0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
128c0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
128d0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
128e0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
128f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
12900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12910 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
12920 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
12930 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
12940 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
12950 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
12960 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
12970 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
12980 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
12990 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
129a0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
129b0 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73  ared.)^.*/.int s
129c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
129d0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
129e0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
129f0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
12a00 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
12a10 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
12a20 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
12a30 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
12a40 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
12a50 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
12a60 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
12a70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
12a80 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
12a90 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
12aa0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
12ab0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
12ac0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
12ad0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
12ae0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
12af0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
12b00 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
12b10 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
12b20 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
12b30 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
12b40 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
12b50 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
12b60 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
12b70 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
12b80 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
12b90 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
12ba0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
12bb0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
12bc0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
12bd0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
12be0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
12bf0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
12c00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
12c10 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
12c20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
12c30 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
12c40 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
12c50 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
12c60 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
12c70 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
12c80 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
12c90 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
12ca0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
12cb0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
12cc0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
12cd0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
12ce0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
12cf0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
12d00 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
12d10 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
12d20 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
12d30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
12d40 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
12d50 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
12d60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
12d70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
12d80 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
12d90 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
12da0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
12db0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12dc0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
12dd0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
12de0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
12df0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
12e00 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
12e10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
12e20 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
12e30 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
12e40 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
12e50 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
12e60 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
12e70 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
12e80 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
12e90 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
12ea0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
12eb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12ec0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
12ed0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
12ee0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
12ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12f00 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
12f10 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
12f20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
12f30 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
12f40 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
12f50 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
12f60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
12f70 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
12f80 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
12f90 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
12fa0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
12fb0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
12fc0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
12fd0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
12fe0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
12ff0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
13000 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
13010 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
13020 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
13030 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
13040 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
13050 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13060 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
13070 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13080 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
13090 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
130a0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
130b0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
130c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
130d0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
130e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
130f0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
13100 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13110 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
13120 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13130 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
13140 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
13150 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
13160 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
13170 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13180 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
13190 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
131a0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
131b0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
131c0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
131d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
131e0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
131f0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
13200 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
13210 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
13220 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
13230 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
13240 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
13250 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
13260 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
13270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
13280 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
13290 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
132a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
132b0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75  le(),.** it shou
132c0 6c 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75  ld pass the resu
132d0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
132e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
132f0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
13300 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
13310 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
13320 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
13330 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
13340 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
13350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
13360 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
13370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
13380 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
13390 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
133a0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
133b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
133c0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
133d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
133e0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
133f0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
13400 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
13410 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
13420 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67   ^(The sqlite3_g
13430 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
13440 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
13450 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
13460 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
13470 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
13480 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
13490 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
134a0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
134b0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
134c0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
134d0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
134e0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
134f0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
13500 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
13510 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
13520 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
13530 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
13540 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
13550 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
13560 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
13570 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
13580 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
13590 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
135a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
135b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
135c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
135d0 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69  rrmsg()].)^.*/.i
135e0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
135f0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
13600 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
13610 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
13620 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
13630 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
13640 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
13650 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
13660 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
13670 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
13680 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
13690 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
136a0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
136b0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
136c0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
136d0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
136e0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
136f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
13700 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
13710 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
13720 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
13730 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
13740 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
13750 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
13760 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
13770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13780 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
13790 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
137a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
137b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
137c0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
137d0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
137e0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
137f0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
13800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
13810 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
13820 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
13830 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13840 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
13850 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
13860 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
13870 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
13880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
13890 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
138a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
138b0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
138c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
138d0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
138e0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
138f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
13900 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
13910 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
13920 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
13930 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
13940 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
13950 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
13960 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
13970 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33  .** ^(In sqlite3
13980 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
13990 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
139a0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
139b0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
139c0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
139d0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
139e0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
139f0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
13a00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
13a10 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
13a20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
13a30 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
13a40 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
13a50 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
13a60 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
13a70 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
13a80 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
13a90 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
13aa0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
13ab0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
13ac0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
13ad0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
13ae0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
13af0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
13b00 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
13b10 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
13b20 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
13b30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
13b40 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
13b50 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
13b60 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
13b70 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
13b80 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
13b90 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
13ba0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
13bb0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
13bc0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
13bd0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
13be0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
13bf0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
13c00 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
13c10 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
13c20 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
13c30 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
13c40 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
13c50 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
13c60 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
13c70 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
13c80 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
13c90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
13ca0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
13cb0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
13cc0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
13cd0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
13ce0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13cf0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13d00 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13d10 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13d20 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13d30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
13d40 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
13d50 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
13d60 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
13d70 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
13d80 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
13d90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13da0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
13db0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
13dc0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
13dd0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13de0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13df0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13e00 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13e10 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13e20 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13e30 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
13e40 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
13e50 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
13e60 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
13e70 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
13e80 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
13e90 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
13ea0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
13eb0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
13ec0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
13ed0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
13ee0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
13ef0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
13f00 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
13f10 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
13f20 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
13f30 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
13f40 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
13f50 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
13f60 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
13f70 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
13f80 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
13f90 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
13fa0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
13fb0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
13fc0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
13fd0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
13fe0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
13ff0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
14000 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
14010 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14020 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
14030 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
14040 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
14050 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14060 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
14070 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
14080 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
14090 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
140a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
140b0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
140c0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
140d0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
140e0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
140f0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
14100 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
14110 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
14120 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
14130 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
14140 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14150 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
14160 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
14170 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
14180 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
14190 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
141a0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
141b0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
141c0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
141d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
141e0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
141f0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
14200 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
14210 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
14220 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14230 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
14240 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
14250 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
14260 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
14270 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
14280 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
14290 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
142a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
142b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
142c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
142d0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
142e0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
142f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14300 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
14310 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
14320 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
14330 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
14340 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
14350 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
14360 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
14370 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
14380 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
14390 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
143a0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
143b0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
143c0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
143d0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
143e0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
143f0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
14400 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
14410 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
14420 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
14430 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
14440 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
14450 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
14460 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
14470 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
14480 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
14490 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
144a0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
144b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
144c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
144d0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
144e0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
144f0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
14500 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
14510 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
14520 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
14530 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
14540 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
14550 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14560 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
14570 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
14580 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
14590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
145a0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
145b0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
145c0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
145d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
145e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
145f0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
14600 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
14610 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
14620 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
14630 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
14640 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
14650 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
14660 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
14670 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
14680 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
14690 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
146a0 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
146b0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
146c0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
146d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
146e0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
146f0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
14700 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
14710 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
14720 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
14730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14740 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
14750 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
14760 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
14770 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
14780 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
14790 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
147a0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
147b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
147c0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
147d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
147e0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
147f0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
14800 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
14810 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
14820 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
14830 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
14840 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
14850 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
14860 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
14870 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
14880 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
14890 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
148a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
148b0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
148c0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
148d0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
148e0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
148f0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
14900 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
14910 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
14920 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
14930 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
14940 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
14950 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
14960 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
14970 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
14980 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
14990 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
149a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
149b0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
149c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
149d0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
149e0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
149f0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
14a00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
14a10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14a20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
14a30 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
14a40 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
14a50 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
14a60 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
14a70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
14a80 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
14a90 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
14aa0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
14ab0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
14ac0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
14ad0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
14ae0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
14af0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
14b00 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
14b10 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
14b20 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
14b30 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
14b40 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
14b50 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
14b60 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
14b70 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
14b80 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
14b90 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
14ba0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
14bb0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
14bc0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
14bd0 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
14be0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
14bf0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
14c00 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
14c10 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
14c20 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
14c30 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
14c40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
14c50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14c60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
14c70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14c80 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
14c90 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
14ca0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
14cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
14cc0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14cd0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
14ce0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
14cf0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
14d00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14d10 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
14d20 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
14d30 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
14d40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14d50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
14d60 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
14d70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
14d80 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
14d90 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
14da0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
14db0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
14dc0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
14dd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14de0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
14df0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
14e00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
14e10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14e20 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
14e30 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
14e40 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
14e50 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
14e60 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
14e70 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
14e80 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
14e90 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
14ea0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14eb0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
14ec0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
14ed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
14ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ef0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
14f00 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
14f10 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
14f20 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
14f30 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
14f40 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
14f50 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
14f60 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14f70 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
14f80 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
14f90 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
14fa0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
14fb0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
14fc0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
14fd0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14fe0 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
14ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
15000 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
15010 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
15020 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
15030 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
15040 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
15050 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
15060 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
15070 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
15080 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
15090 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
150a0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
150b0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
150c0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
150d0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
150e0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
150f0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
15100 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
15110 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
15120 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
15130 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
15140 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
15150 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
15160 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
15170 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
15180 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
15190 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
151a0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
151b0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
151c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
151d0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
151e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
151f0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
15200 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
15210 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
15220 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
15230 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
15240 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
15250 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
15260 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
15270 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
15280 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
15290 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
152a0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
152b0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
152c0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
152d0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
152e0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
152f0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
15300 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
15310 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
15320 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
15330 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
15340 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
15350 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
15360 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
15370 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
15380 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
15390 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
153a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
153b0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
153c0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
153d0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
153e0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
153f0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
15410 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15420 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
15430 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
15440 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
15450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
15460 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
15470 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
15480 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
15490 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
154a0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
154b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
154c0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
154d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
154e0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
154f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
15500 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
15510 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
15520 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
15530 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
15540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
15550 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
15560 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
15570 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
15580 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
15590 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
155a0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
155b0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
155c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
155d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
155e0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
155f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
15600 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
15610 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
15620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15630 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
15640 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
15650 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
15660 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
15670 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
15680 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
15690 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
156a0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
156b0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
156c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
156d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
156e0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
156f0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
15700 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
15710 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15720 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
15730 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
15740 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
15750 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
15760 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
15770 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15780 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
15790 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
157a0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
157b0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
157c0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
157d0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
157e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
157f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
15800 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
15810 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
15820 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
15830 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
15840 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
15850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
15860 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
15870 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
15880 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
15890 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
158a0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
158b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
158c0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
158d0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
158e0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
158f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15900 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
15910 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
15920 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
15930 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15940 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
15950 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
15960 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
15970 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
15980 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
15990 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
159a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
159b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
159c0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
159d0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
159e0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
159f0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
15a00 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
15a10 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
15a20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
15a30 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
15a40 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
15a50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
15a60 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
15a70 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
15a80 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
15a90 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
15aa0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
15ab0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
15ac0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
15ad0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
15ae0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
15af0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
15b00 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
15b10 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
15b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
15b30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
15b40 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
15b50 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
15b60 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
15b70 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
15b80 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
15b90 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
15ba0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
15bb0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
15bc0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
15bd0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
15be0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
15bf0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
15c00 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
15c10 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
15c20 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
15c30 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
15c40 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
15c50 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
15c60 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
15c70 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
15c80 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
15c90 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
15ca0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
15cb0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
15cc0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
15cd0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
15ce0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
15cf0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
15d00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15d10 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
15d20 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
15d30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
15d40 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
15d50 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
15d60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
15d70 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
15d80 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
15d90 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
15da0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
15db0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15dc0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
15dd0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
15de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
15df0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
15e00 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
15e10 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
15e20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15e30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
15e40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
15e50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
15e60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15e70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
15e80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
15e90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
15ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
15eb0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
15ec0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
15ed0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
15ef0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
15f00 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
15f10 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
15f20 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
15f30 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
15f40 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
15f50 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
15f60 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
15f70 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
15f80 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
15f90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
15fa0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
15fb0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
15fc0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
15fd0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
15fe0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
15ff0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
16000 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
16010 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
16020 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
16030 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
16040 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
16050 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
16060 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
16070 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
16080 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
16090 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
160a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
160b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
160c0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
160d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
160e0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
160f0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
16100 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
16110 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
16120 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16130 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16140 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
16150 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
16160 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
16170 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
16180 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
16190 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
161a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
161b0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
161c0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
161d0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
161e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
161f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
16200 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
16210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16220 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
16230 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
16240 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
16250 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
16260 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
16270 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
16280 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
16290 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
162a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
162b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
162c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
162d0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
162e0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
162f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
16300 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16310 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
16320 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
16330 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
16340 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
16350 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
16360 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
16370 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
16380 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
16390 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
163a0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
163b0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
163c0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
163d0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
163e0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
163f0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
16400 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
16410 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
16420 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
16430 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
16440 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
16450 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
16460 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
16470 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
16480 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16490 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
164a0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
164b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
164c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
164d0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
164e0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
164f0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
16500 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
16510 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
16520 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
16530 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
16540 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
16550 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
16560 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
16570 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
16580 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
16590 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
165a0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
165b0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
165c0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
165d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
165e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
165f0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
16600 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
16610 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
16620 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
16630 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
16640 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
16650 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
16660 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
16670 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
16680 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
16690 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
166a0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
166b0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
166c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
166d0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
166e0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
166f0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
16700 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
16710 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16720 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
16730 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
16740 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
16750 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
16760 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
16770 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
16780 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
16790 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
167a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
167b0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
167c0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
167d0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
167e0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
167f0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
16800 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
16810 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
16820 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
16830 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
16840 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
16850 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
16860 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
16870 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
16880 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
16890 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
168a0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
168b0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
168c0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
168d0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
168e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
168f0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
16900 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
16910 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
16920 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
16930 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
16940 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
16950 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
16960 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
16970 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
16980 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
16990 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
169a0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
169b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
169c0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
169d0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
169e0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
169f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
16a00 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
16a10 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
16a20 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
16a30 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
16a40 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
16a50 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
16a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
16a70 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
16a80 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
16a90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16aa0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
16ab0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
16ac0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
16ad0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
16ae0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
16af0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
16b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
16b10 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
16b20 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
16b30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16b40 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
16b50 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
16b60 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16b80 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
16b90 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
16ba0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
16bb0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
16bc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
16bd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
16be0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
16bf0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
16c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
16c10 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
16c20 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
16c30 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
16c40 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
16c50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16c60 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
16c70 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
16c80 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
16c90 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
16ca0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
16cb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
16cc0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
16cd0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
16ce0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16cf0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
16d00 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
16d10 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
16d20 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
16d30 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
16d40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
16d50 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
16d60 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
16d70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16d80 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
16d90 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
16da0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
16db0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
16dc0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
16dd0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
16de0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
16df0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
16e00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16e10 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
16e20 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
16e30 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
16e40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
16e50 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
16e60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
16e70 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
16e80 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
16e90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
16ea0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
16eb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
16ec0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
16ed0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
16ee0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
16ef0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
16f00 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
16f10 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
16f20 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
16f30 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
16f40 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
16f50 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
16f60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16f70 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
16f80 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
16f90 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
16fa0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
16fb0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
16fc0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
16fd0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
16fe0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
16ff0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
17000 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
17010 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
17020 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17030 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17040 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
17050 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
17060 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
17070 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
17080 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
17090 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
170a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
170b0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
170c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
170d0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
170e0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
170f0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
17100 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
17110 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17120 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
17130 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
17140 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
17150 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
17160 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
17170 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
17180 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
17190 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
171a0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
171b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
171c0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
171d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
171e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
171f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
17200 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
17210 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
17220 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
17230 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
17240 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
17250 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
17260 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
17270 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
17280 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
17290 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
172a0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
172b0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
172c0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
172d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
172e0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
172f0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
17300 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
17310 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
17320 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
17330 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
17340 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
17350 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
17360 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
17370 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
17380 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 35 74 68  meter.  ^The 5th
17390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
173a0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
173b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
173c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
173d0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
173e0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
173f0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 5e  f applicable.  ^
17400 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
17410 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
17430 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
17440 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
17450 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
17460 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
17470 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
17480 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
17490 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
174a0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
174b0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
174c0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
174d0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
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 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
17510 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
17520 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
17530 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
17540 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
17550 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17560 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17580 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
17590 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
175a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
175b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
175c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
175d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
175e0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
175f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
17600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17620 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
17630 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
17640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17650 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17670 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
17680 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
17690 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
176a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
176b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
176c0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
176d0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
176e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
176f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17710 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
17720 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
17730 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
17740 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17760 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
17770 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
17780 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
17790 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
177a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
177b0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
177c0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
177d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
177e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
177f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17800 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
17810 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
17820 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
17830 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17840 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
17850 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
17860 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
17870 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17880 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17890 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
178a0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
178b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
178c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
178d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
178e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
178f0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
17900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17910 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17930 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
17940 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
17950 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
17960 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17970 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17980 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
17990 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
179a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
179b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
179c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
179d0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
179e0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
179f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
17a00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17a10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17a20 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
17a30 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
17a40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
17a50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a70 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
17a80 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
17a90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17aa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ac0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
17ad0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
17ae0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
17af0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
17b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b10 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
17b20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
17b30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
17b40 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
17b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17b60 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
17b70 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
17b80 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
17b90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
17bb0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
17bc0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
17bd0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
17be0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
17c00 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
17c10 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
17c20 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
17c30 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
17c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
17c50 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
17c60 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
17c70 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
17c80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
17ca0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
17cb0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
17cc0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
17cd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17ce0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
17cf0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17d00 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
17d10 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
17d20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17d30 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
17d40 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
17d50 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
17d60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17d70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17d80 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
17d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
17da0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17db0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17dc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17dd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
17de0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
17df0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17e00 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
17e10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17e20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
17e30 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
17e40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17e50 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
17e60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17e70 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
17e80 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
17e90 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
17ea0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
17eb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17ec0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
17ed0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
17ee0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
17ef0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
17f00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17f10 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
17f20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
17f30 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
17f40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17f50 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
17f60 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
17f70 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ons.** EXPERIMEN
17f80 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
17f90 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
17fa0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
17fb0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
17fc0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
17fd0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
17fe0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
17ff0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18000 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
18010 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18020 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
18030 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
18040 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
18050 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
18060 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
18070 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
18080 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
18090 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
180a0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
180b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
180c0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
180d0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
180e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
180f0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
18100 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
18110 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
18120 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
18130 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
18140 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
18150 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
18160 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
18170 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
18180 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
18190 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
181a0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
181b0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
181c0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
181d0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
181e0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
181f0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
18200 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
18210 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
18220 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
18230 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
18240 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
18250 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
18260 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
18270 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
18280 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
18290 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
182a0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
182b0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
182c0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
182d0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  n..*/.SQLITE_EXP
182e0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
182f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
18300 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
18310 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
18320 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
18330 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
18340 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
18350 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
18360 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
18370 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
18380 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
18390 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
183a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
183b0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
183c0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
183d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
183e0 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
183f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18400 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
18410 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
18420 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
18430 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
18440 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
18450 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
18460 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
18470 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
18480 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
18490 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
184a0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
184b0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
184c0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
184d0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
184e0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
184f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
18500 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
18510 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
18520 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
18530 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
18540 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
18550 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
18560 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
18570 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
18580 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
18590 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
185a0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
185b0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
185c0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
185d0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
185e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
185f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
18600 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
18610 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
18620 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
18630 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
18640 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
18650 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
18660 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
18670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
18680 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
18690 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
186a0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
186b0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
186c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
186d0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
186e0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
186f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
18700 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
18710 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
18720 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
18730 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
18740 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
18750 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
18760 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
18770 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
18780 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
18790 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
187a0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
187b0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
187c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
187d0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
187e0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
187f0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
18800 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
18810 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
18820 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
18830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18840 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
18850 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
18860 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
18870 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
18880 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
18890 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
188a0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
188b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
188c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
188d0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
188e0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
188f0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
18900 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
18910 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
18920 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
18930 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
18940 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
18950 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
18960 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
18970 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
18980 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
18990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
189a0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
189b0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
189c0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
189d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
189e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
189f0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
18a00 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
18a10 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
18a20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
18a30 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
18a40 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
18a50 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
18a60 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
18a70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
18a80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
18a90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
18aa0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
18ab0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
18ac0 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
18ad0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
18ae0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
18af0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
18b00 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
18b10 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
18b20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
18b30 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
18b40 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
18b50 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
18b60 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
18b70 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
18b80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
18b90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
18ba0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
18bb0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
18bc0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
18bd0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
18be0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
18bf0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
18c00 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
18c10 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
18c20 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
18c30 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
18c40 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
18c50 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
18c60 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
18c70 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
18c80 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
18c90 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
18ca0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
18cb0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
18cc0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
18cd0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
18ce0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
18cf0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
18d00 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
18d10 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
18d20 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
18d30 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
18d40 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
18d50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
18d60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
18d70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
18d80 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51  ],.** and/or [SQ
18d90 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
18da0 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e  ECACHE] flags:)^
18db0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
18dc0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
18dd0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
18de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
18df0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
18e00 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
18e10 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
18e20 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
18e30 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
18e40 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
18e50 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
18e60 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
18e70 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
18e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
18e90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18ea0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
18eb0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
18ec0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
18ed0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
18ee0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
18ef0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
18f00 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
18f10 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
18f20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
18f30 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
18f40 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
18f50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
18f60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
18f70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
18f80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
18f90 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
18fa0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
18fb0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
18fc0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
18fd0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
18fe0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
18ff0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
19000 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
19010 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
19020 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
19030 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
19040 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
19050 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
19060 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
19070 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
19080 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
19090 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
190a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
190b0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
190c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
190d0 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65  own above or one
190e0 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74   of the combinat
190f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
19100 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74   combined.** wit
19110 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
19120 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
19130 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
19140 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TEX],.** [SQLITE
19150 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
19160 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  E] and/or [SQLIT
19170 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
19180 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68  HE] flags,.** th
19190 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
191a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
191b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
191c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
191d0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
191e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
191f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
19200 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
19210 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
19220 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
19230 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
19240 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
19250 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
19260 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
19270 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
19280 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
19290 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
192a0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
192b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
192c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
192d0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
192e0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
192f0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
19300 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
19310 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19320 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
19330 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
19340 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
19350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
19360 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
19370 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
19380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
19390 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
193a0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
193b0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
193c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
193d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
193e0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
193f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
19400 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
19410 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
19420 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
19430 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
19440 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
19450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19460 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
19470 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
19480 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
19490 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
194a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  bled..**.** ^If 
194b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
194c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
194d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
194e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
194f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
19500 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
19510 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
19520 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
19530 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
19540 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
19550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19560 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
19570 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
19580 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
19590 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
195a0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
195b0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
195c0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
195d0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
195e0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
195f0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
19600 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
19610 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
19620 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
19630 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
19640 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
19650 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
19660 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
19670 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
19680 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
19690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
196a0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
196b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
196c0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
196d0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
196e0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
196f0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
19700 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
19710 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
19720 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
19730 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
19740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19750 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
19760 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
19770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19780 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
19790 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
197a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
197b0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
197c0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
197d0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
197e0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
197f0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
19800 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
19810 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
19820 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
19830 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
19840 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
19850 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
19860 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
19870 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
19880 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
19890 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
198a0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
198b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
198c0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
198d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
198e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
198f0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
19900 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
19910 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
19920 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
19930 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
19940 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
19950 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
19960 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
19970 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
19980 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
19990 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
199a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
199b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
199c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
199d0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
199e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
199f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
19a00 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
19a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
19a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
19a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
19a40 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
19a50 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
19a60 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
19a70 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
19a80 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
19a90 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
19aa0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
19ab0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
19ac0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
19ad0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
19ae0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
19af0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
19b00 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
19b10 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
19b20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
19b30 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
19b40 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
19b50 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
19b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
19b70 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
19b80 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
19b90 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
19ba0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
19bb0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
19bc0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
19bd0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
19be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19bf0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
19c00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
19c10 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
19c20 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
19c30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
19c40 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
19c50 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
19c60 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
19c70 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
19c80 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
19c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
19ca0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
19cb0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
19cc0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
19cd0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
19ce0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
19cf0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
19d00 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
19d10 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
19d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
19d30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
19d40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
19d50 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
19d60 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
19d70 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
19d80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
19d90 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
19da0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
19db0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
19dc0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
19dd0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
19de0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
19df0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
19e00 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
19e10 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
19e20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
19e30 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
19e40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
19e50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
19e60 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
19e70 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
19e80 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
19e90 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
19ea0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
19eb0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
19ec0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
19ed0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
19ee0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
19ef0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
19f00 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
19f10 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
19f20 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
19f30 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19f40 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
19f50 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
19f60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
19f70 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
19f80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
19f90 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
19fa0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
19fb0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
19fc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
19fd0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19fe0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
19ff0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1a000 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1a010 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1a020 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1a030 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1a040 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1a050 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1a060 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1a070 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1a080 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1a090 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1a0a0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1a0b0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1a0c0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1a0d0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1a0e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1a0f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1a100 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1a110 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1a120 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1a130 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1a140 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1a150 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1a160 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1a170 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1a180 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1a190 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1a1a0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1a1b0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1a1c0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1a1d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1a1e0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1a1f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1a200 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1a210 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1a220 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1a230 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1a240 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1a250 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1a260 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1a270 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1a280 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
1a290 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1a2a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1a2b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
1a2c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
1a2d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
1a2e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1a2f0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
1a300 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1a310 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1a320 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a330 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1a340 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
1a350 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a370 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1a380 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1a390 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1a3a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1a3b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1a3c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1a3d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1a3e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1a3f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1a400 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1a410 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1a420 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1a430 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1a440 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1a450 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1a460 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1a470 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1a480 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1a490 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1a4a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1a4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a4c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1a4d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1a4e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1a4f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1a500 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1a510 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1a520 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1a530 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1a540 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1a550 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1a560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1a570 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1a580 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1a590 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1a5a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1a5b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1a5c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1a5d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1a5e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1a5f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1a600 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1a610 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1a620 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1a630 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1a640 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1a650 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1a660 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1a670 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1a680 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1a690 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1a6a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1a6b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1a6c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1a6d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
1a6e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1a6f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1a700 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1a710 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1a720 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1a730 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1a740 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1a750 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1a760 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1a770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1a780 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1a790 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1a7a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1a7b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a7c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1a7d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1a7e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1a7f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1a800 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1a810 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1a820 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1a830 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1a840 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1a850 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f  ct.  The functio
1a860 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c  n returns the ol
1a870 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a  d limit.)^.**.**
1a880 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
1a890 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
1a8a0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
1a8b0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
1a8c0 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69  .** ^(For the li
1a8d0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20  mit category of 
1a8e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a  SQLITE_LIMIT_XYZ
1a8f0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
1a900 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
1a910 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
1a920 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
1a930 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73  time C preproces
1a940 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  sor macro named 
1a950 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
1a960 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a  LITE_MAX_XYZ]..*
1a970 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
1a980 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
1a990 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
1a9a0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
1a9b0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1a9c0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1a9d0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1a9e0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1a9f0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1aa00 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
1aa10 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  imit..**.** Run-
1aa20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1aa30 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1aa40 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1aa50 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1aa60 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1aa70 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1aa80 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1aa90 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1aaa0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1aab0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1aac0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1aad0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1aae0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1aaf0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
1ab00 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1ab10 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1ab20 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1ab30 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1ab40 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1ab50 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1ab60 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1ab70 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1ab80 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1ab90 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1aba0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1abb0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1abc0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1abd0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1abe0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1abf0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1ac00 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1ac10 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1ac20 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1ac30 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1ac40 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1ac50 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1ac60 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1ac70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1ac80 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1ac90 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1aca0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1acb0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1acc0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1acd0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1ace0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1acf0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1ad00 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1ad10 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1ad20 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1ad30 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1ad40 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1ad50 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1ad60 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1ad70 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
1ad80 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
1ad90 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
1ada0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
1adb0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1adc0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
1add0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
1ade0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
1adf0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
1ae00 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1ae10 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1ae20 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
1ae30 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
1ae40 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1ae50 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
1ae60 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
1ae70 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1ae80 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
1ae90 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1aea0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1aeb0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
1aec0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
1aed0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
1aee0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
1aef0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
1af00 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
1af10 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  dl>.** ^(<dt>SQL
1af20 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1af30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1af40 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
1af50 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
1af60 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
1af70 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  .<dd>)^.**.** ^(
1af80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1af90 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1afa0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1afb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1afc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1afd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1afe0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1aff0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
1b000 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b010 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1b020 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
1b030 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
1b040 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
1b050 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
1b060 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1b070 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1b080 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
1b090 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
1b0a0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
1b0b0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
1b0c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1b0d0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1b0e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1b0f0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1b100 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1b110 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1b120 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1b130 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1b140 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1b150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b160 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1b170 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1b180 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1b190 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
1b1a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b1b0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1b1c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b1d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1b1e0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
1b1f0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
1b200 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
1b210 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1b220 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
1b230 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1b240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b250 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1b260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b270 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1b280 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1b290 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1b2a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b2b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1b2c0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1b2d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1b2e0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1b2f0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1b300 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ses].</dd>.**.**
1b310 20 5e 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d   ^<dt>SQLITE_LIM
1b320 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1b330 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1b340 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1b350 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1b360 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1b370 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
1b380 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
1b390 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
1b3a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b3b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1b3c0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1b3d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b3e0 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1b3f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1b400 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1b410 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e  be bound.</dd>)^
1b420 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1b430 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1b440 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1b450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b460 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1b470 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1b480 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1b490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b4a0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1b4b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b4c0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1b4d0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1b4e0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1b4f0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1b500 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1b510 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1b520 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1b530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1b540 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1b550 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1b560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1b570 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1b580 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1b590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1b5a0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1b5b0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1b5c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1b5d0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1b5e0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1b5f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1b600 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1b610 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1b620 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1b630 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1b640 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1b650 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b660 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1b670 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1b680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b690 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1b6a0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1b6b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b6c0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1b6d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1b6e0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1b6f0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1b700 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1b710 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1b720 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1b730 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1b740 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1b750 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1b760 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1b770 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1b780 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1b790 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1b7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1b7b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1b7c0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1b7d0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1b7e0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1b7f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1b800 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1b810 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1b820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b830 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1b840 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1b850 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1b860 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1b870 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1b880 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1b890 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1b8a0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1b8b0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1b8c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1b8d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1b8e0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1b8f0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1b900 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1b910 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1b920 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b930 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1b940 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1b950 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1b960 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1b970 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1b980 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1b990 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1b9a0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1b9b0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1b9c0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1b9d0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1b9e0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1b9f0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1ba00 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1ba10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1ba20 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1ba30 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1ba40 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1ba50 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1ba60 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1ba70 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1ba80 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1ba90 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1baa0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1bab0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1bac0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1bad0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1bae0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1baf0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1bb00 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1bb10 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1bb20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1bb30 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1bb40 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1bb50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1bb60 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1bb70 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1bb80 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1bb90 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1bba0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1bbb0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1bbc0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1bbd0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1bbe0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1bbf0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1bc00 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1bc10 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1bc20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1bc30 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1bc40 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1bc50 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1bc60 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1bc70 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1bc80 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1bc90 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1bca0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1bcb0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1bcc0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1bcd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1bce0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1bcf0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bd00 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1bd10 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1bd20 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1bd30 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1bd40 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1bd50 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1bd60 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1bd70 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1bd80 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1bd90 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1bda0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1bdb0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1bdc0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1bdd0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1bde0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1bdf0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1be00 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1be10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1be20 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1be30 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1be40 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1be50 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1be60 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1be70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1be80 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1be90 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1bea0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1beb0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1bec0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1bed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1bef0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1bf00 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1bf10 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1bf20 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1bf30 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1bf40 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1bf50 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1bf60 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1bf70 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1bf80 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1bf90 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1bfa0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1bfb0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1bfc0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1bfd0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1bfe0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1bff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1c000 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1c010 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1c020 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1c030 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1c040 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1c050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1c060 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1c070 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1c080 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1c090 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1c0a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1c0b0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1c0c0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1c0d0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1c0e0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1c0f0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1c100 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1c110 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1c120 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1c130 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1c140 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1c150 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74  it again.  ^If t
1c160 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
1c170 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
1c180 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
1c190 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
1c1a0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
1c1b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1c1c0 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
1c1d0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1c1e0 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
1c1f0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1c200 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
1c210 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
1c220 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
1c230 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
1c240 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1c250 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1c260 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1c270 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1c280 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1c290 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1c2a0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1c2b0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1c2c0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1c2d0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1c2e0 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
1c2f0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1c300 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
1c310 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
1c320 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
1c330 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
1c340 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
1c350 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
1c360 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
1c370 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
1c380 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
1c390 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
1c3a0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
1c3b0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
1c3c0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
1c3d0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
1c3e0 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68   and you would h
1c3f0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
1c400 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
1c410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
1c420 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69  n order.** to fi
1c430 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
1c440 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
1c450 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
1c460 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
1c470 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1c480 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
1c490 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
1c4a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1c4b0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
1c4c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1c4d0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f   ^If the value o
1c4e0 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c  f a [parameter |
1c4f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
1c500 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c   in the WHERE cl
1c510 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68  ause might.** ch
1c520 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70  ange the query p
1c530 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
1c540 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74  ent, then the st
1c550 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a  atement may be.*
1c560 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1c570 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69  recompiled (as i
1c580 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
1c590 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1c5a0 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a  ) on the first .
1c5b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1c5c0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
1c5d0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f  ng any change to
1c5e0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1c5f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
1c600 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b  ndings] of the [
1c610 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
1c620 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
1c630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1c640 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1c650 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1c670 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1c680 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1c690 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1c6a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1c6b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1c6d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1c6e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1c6f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1c700 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1c710 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1c720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1c730 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1c740 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1c750 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1c760 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1c770 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1c780 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1c790 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1c7a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1c7b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1c7c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1c7d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1c7e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1c7f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1c800 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1c810 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1c820 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1c830 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1c840 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1c850 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1c860 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1c870 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1c880 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1c890 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1c8a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1c8b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1c8c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c8d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c8e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1c8f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1c900 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1c910 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1c920 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1c930 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1c940 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1c950 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1c960 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1c970 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1c980 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1c990 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1c9a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1c9b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1c9c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1c9d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1c9e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1c9f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1ca00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1ca10 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1ca20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ca30 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1ca40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ca50 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1ca60 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1ca70 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1ca80 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1ca90 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1caa0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1cab0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1cac0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1cad0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1cae0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1caf0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1cb00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1cb10 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1cb20 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1cb30 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1cb40 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
1cb50 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
1cb60 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1cb70 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
1cb80 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1cb90 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1cba0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1cbb0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1cbc0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1cbd0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1cbe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1cbf0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1cc00 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1cc10 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1cc20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cc30 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1cc40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1cc50 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1cc60 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1cc70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1cc80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1cc90 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
1cca0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
1ccb0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1ccc0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1ccd0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1cce0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ccf0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1cd00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1cd10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1cd20 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1cd30 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1cd40 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1cd50 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1cd60 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1cd70 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1cd80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1cd90 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
1cda0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1cdb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1cdc0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
1cdd0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
1cde0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
1cdf0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
1ce00 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
1ce10 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
1ce20 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
1ce30 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
1ce40 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
1ce50 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
1ce60 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1ce70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1ce80 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
1ce90 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1cea0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
1ceb0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
1cec0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1ced0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1cee0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
1cef0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
1cf00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
1cf10 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
1cf20 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
1cf30 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1cf40 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1cf50 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1cf60 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1cf70 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1cf80 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1cf90 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1cfa0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1cfb0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1cfc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1cfd0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1cfe0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1cff0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1d000 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1d010 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1d020 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1d030 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1d040 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1d050 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1d060 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
1d070 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d080 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
1d090 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1d0a0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1d0b0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
1d0c0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
1d0d0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
1d0e0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
1d0f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1d100 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1d110 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1d120 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
1d130 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1d140 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1d150 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1d160 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1d170 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1d180 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1d190 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1d1a0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
1d1b0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
1d1c0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1d1d0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
1d1e0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1d1f0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
1d200 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1d210 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
1d220 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1d230 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1d240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d250 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1d260 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1d270 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
1d280 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1d290 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1d2a0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1d2b0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1d2c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1d2d0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
1d2e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1d2f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
1d300 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
1d310 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1d320 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1d330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1d340 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1d350 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1d360 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1d370 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1d380 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1d390 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1d3a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1d3b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d3c0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
1d3d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
1d3e0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
1d3f0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
1d400 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
1d410 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1d420 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
1d430 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1d440 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1d450 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
1d460 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
1d470 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
1d480 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
1d490 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
1d4a0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
1d4b0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
1d4c0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
1d4d0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
1d4e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1d4f0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
1d500 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
1d510 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
1d520 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
1d530 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
1d540 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1d550 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1d560 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1d570 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1d580 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
1d590 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
1d5a0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
1d5b0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
1d5c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1d5d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
1d5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
1d5f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
1d600 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
1d610 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
1d620 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
1d630 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
1d640 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
1d650 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
1d660 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
1d670 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
1d680 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
1d690 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1d6a0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
1d6b0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
1d6c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
1d6d0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
1d6e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1d6f0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
1d700 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1d710 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1d720 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1d730 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1d740 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1d750 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1d760 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1d770 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1d780 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
1d790 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
1d7a0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
1d7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1d7c0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
1d7d0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
1d7e0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
1d7f0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
1d800 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
1d810 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
1d820 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
1d830 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1d840 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1d850 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1d860 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1d870 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1d880 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
1d890 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
1d8a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
1d8b0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
1d8c0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
1d8d0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
1d8e0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e  meric identifer.
1d8f0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
1d900 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
1d910 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1d920 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1d930 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
1d940 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1d950 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1d960 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1d970 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1d980 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1d990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1d9a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1d9b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1d9c0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
1d9d0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
1d9e0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1d9f0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
1da00 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
1da10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da20 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
1da30 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
1da40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1da50 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1da60 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
1da70 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
1da80 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
1da90 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
1daa0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1dab0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
1dac0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1dad0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1dae0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1daf0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1db00 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1db10 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1db20 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1db30 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1db40 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
1db50 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
1db60 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
1db70 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
1db80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1db90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1dba0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
1dbb0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
1dbc0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
1dbd0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
1dbe0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
1dbf0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
1dc00 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1dc10 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
1dc20 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1dc30 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
1dc40 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1dc50 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
1dc60 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
1dc70 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
1dc80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1dc90 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1dca0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1dcb0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
1dcc0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1dcd0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1dce0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1dcf0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1dd00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1dd10 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1dd20 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1dd30 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1dd40 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1dd50 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1dd60 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1dd70 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1dd80 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
1dd90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1dda0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1ddb0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1ddc0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1ddd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1dde0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1ddf0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1de00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
1de10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1de20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1de30 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1de40 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1de50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1de60 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1de70 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1de80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1de90 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1dea0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1deb0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1dec0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
1ded0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
1dee0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1def0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1df00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
1df10 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
1df20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1df30 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
1df40 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
1df50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1df60 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
1df70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1df80 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1df90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1dfa0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1dfb0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1dfc0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1dfd0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1dfe0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1dff0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1e000 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1e010 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1e020 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1e030 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1e040 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1e050 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1e060 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1e070 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
1e080 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
1e090 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
1e0a0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
1e0b0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
1e0c0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
1e0d0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1e0e0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1e0f0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1e100 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1e110 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1e120 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
1e130 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
1e140 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
1e150 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1e160 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
1e170 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
1e180 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
1e190 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
1e1a0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
1e1b0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
1e1c0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
1e1d0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
1e1e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1e1f0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
1e200 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1e210 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
1e220 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1e230 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
1e240 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
1e250 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
1e260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1e270 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
1e280 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
1e290 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
1e2a0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
1e2b0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
1e2c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1e2d0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
1e2e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
1e2f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
1e300 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
1e310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1e320 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
1e330 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
1e340 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1e350 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
1e360 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
1e370 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
1e380 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
1e390 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1e3a0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
1e3b0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
1e3c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1e3d0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
1e3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1e3f0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
1e400 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1e410 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
1e420 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
1e430 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
1e440 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
1e450 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1e460 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1e470 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1e480 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1e490 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
1e4a0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
1e4b0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
1e4c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1e4d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1e4e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1e4f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e500 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1e510 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
1e520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e530 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1e540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1e550 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1e560 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1e570 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1e580 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1e590 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1e5a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1e5b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1e5c0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1e5d0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1e5e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1e5f0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1e600 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1e610 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1e620 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1e630 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e640 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1e650 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1e660 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1e670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1e680 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1e690 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1e6a0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1e6b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1e6c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1e6d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1e6e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1e6f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1e700 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1e710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e720 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1e730 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1e740 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1e750 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1e760 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1e770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e780 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1e790 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
1e7a0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
1e7b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
1e7c0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
1e7d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
1e7e0 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
1e7f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
1e800 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
1e810 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
1e820 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
1e830 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
1e840 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
1e850 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
1e860 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1e870 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1e880 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1e890 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1e8a0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1e8b0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1e8c0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
1e8d0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1e8e0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1e8f0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1e900 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
1e910 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
1e920 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1e930 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1e940 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1e950 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1e960 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1e970 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1e980 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
1e990 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
1e9a0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
1e9b0 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
1e9c0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1e9d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1e9e0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1e9f0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1ea00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ea10 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1ea20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ea30 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ea40 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1ea50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ea60 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1ea70 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1ea80 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
1ea90 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
1eaa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1eab0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1eac0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
1ead0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
1eae0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
1eaf0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
1eb00 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
1eb10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1eb20 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
1eb30 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1eb40 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1eb50 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1eb60 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1eb70 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1eb80 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1eb90 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1eba0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1ebb0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1ebc0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1ebd0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1ebe0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1ebf0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1ec00 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1ec10 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
1ec20 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
1ec30 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
1ec40 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
1ec50 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
1ec60 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
1ec70 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
1ec80 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1ec90 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1eca0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1ecb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ecc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1ecd0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1ece0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1ecf0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1ed00 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1ed10 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1ed20 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1ed30 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1ed40 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1ed50 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1ed60 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1ed70 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1ed80 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1ed90 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1eda0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1edb0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1edc0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1edd0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1ede0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1edf0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1ee00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1ee10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1ee20 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1ee30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1ee40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1ee50 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1ee60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ee70 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1ee80 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ee90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1eea0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1eeb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1eec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1eed0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1eee0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1eef0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1ef00 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1ef10 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1ef20 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1ef30 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1ef40 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1ef50 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1ef60 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1ef70 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1ef80 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1ef90 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1efa0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1efb0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1efc0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1efd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1efe0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1eff0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1f000 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1f010 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1f020 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f030 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1f040 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1f050 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1f060 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f070 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1f080 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1f090 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1f0a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1f0b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f0c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1f0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f0e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f0f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1f100 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f110 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1f120 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1f130 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1f140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f150 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1f160 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1f170 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
1f180 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1f190 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1f1a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1f1b0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1f1c0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1f1d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1f1e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1f1f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f200 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
1f210 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1f220 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1f230 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1f240 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1f250 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1f260 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f280 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1f290 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
1f2a0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1f2b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1f2c0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1f2d0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1f2e0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1f2f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
1f300 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1f310 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1f320 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1f330 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1f340 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1f350 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1f360 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
1f370 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1f380 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1f390 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f3a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1f3b0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1f3c0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
1f3d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1f3e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1f3f0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1f400 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1f410 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1f420 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1f430 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1f440 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1f450 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1f460 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f490 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1f4a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1f4b0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1f4c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f4d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1f4e0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1f4f0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
1f500 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1f510 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f520 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1f530 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1f540 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f550 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1f560 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1f570 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1f580 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
1f590 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
1f5a0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
1f5b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1f5c0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1f5d0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1f5e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f5f0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1f600 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1f610 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1f620 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f630 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1f640 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1f650 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1f660 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1f670 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1f680 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
1f690 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1f6a0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1f6b0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1f6c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1f6d0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1f6e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1f6f0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1f700 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1f710 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1f720 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1f730 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1f740 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1f750 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1f760 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1f770 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1f780 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1f790 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1f7a0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1f7b0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1f7c0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1f7d0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1f7e0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1f7f0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1f800 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1f810 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
1f820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1f840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1f850 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1f860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1f870 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1f880 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1f890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1f8a0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1f8b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
1f8c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f8d0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1f8e0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1f8f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
1f900 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
1f910 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1f920 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
1f930 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
1f940 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
1f950 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
1f960 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
1f970 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f980 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1f990 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1f9a0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1f9b0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1f9c0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
1f9d0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1f9e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1f9f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1fa00 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1fa10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1fa20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1fa30 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1fa40 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1fa50 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1fa60 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
1fa70 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1fa80 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
1fa90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1faa0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1fab0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
1fac0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1fad0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
1fae0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1faf0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
1fb00 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
1fb10 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
1fb20 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
1fb30 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
1fb40 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
1fb50 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
1fb60 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
1fb70 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
1fb80 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1fb90 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
1fba0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
1fbb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fbc0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
1fbd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
1fbe0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
1fbf0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
1fc00 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
1fc10 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1fc20 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1fc30 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1fc40 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1fc50 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
1fc60 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
1fc70 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
1fc80 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1fc90 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
1fca0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
1fcb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1fcc0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1fcd0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
1fce0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
1fcf0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
1fd00 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
1fd10 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
1fd20 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
1fd30 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1fd40 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1fd50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fd60 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
1fd70 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
1fd80 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1fd90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
1fda0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
1fdb0 74 61 62 6c 65 0a 2a 2a 20 6f 72 20 63 6f 6c 75  table.** or colu
1fdc0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
1fdd0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
1fde0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
1fdf0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
1fe00 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
1fe10 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
1fe20 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
1fe30 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
1fe40 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
1fe50 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
1fe60 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
1fe70 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
1fe80 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
1fe90 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1fea0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1feb0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1fec0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
1fed0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1fee0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
1fef0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
1ff00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
1ff10 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1ff20 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
1ff30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1ff40 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
1ff50 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
1ff60 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
1ff70 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
1ff80 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1ff90 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
1ffa0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
1ffb0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
1ffc0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
1ffd0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
1ffe0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1fff0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
20000 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
20010 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
20020 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
20030 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
20040 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
20050 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
20060 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
20070 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
20080 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
20090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
200a0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
200b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
200c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
200d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
200e0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
200f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
20100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
20110 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
20120 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
20130 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
20140 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
20150 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
20160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20170 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
20180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
20190 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
201a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
201b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
201c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
201d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
201e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
201f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
20200 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
20210 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
20220 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
20230 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
20240 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
20250 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
20260 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
20270 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
20280 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
20290 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
202a0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
202b0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
202c0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
202d0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
202e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
202f0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
20300 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
20310 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
20320 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
20330 75 72 6e 65 64 2e 29 20 20 5e 49 66 20 74 68 65  urned.)  ^If the
20340 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
20350 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
20360 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
20370 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
20380 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
20390 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
203a0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
203b0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
203c0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
203d0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
203e0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
203f0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
20400 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
20410 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
20420 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
20430 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
20440 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
20450 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
20460 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
20470 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
20480 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
20490 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
204a0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
204b0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
204c0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
204d0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
204e0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
204f0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
20500 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
20510 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
20520 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
20530 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
20540 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
20550 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
20560 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
20570 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
20580 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
20590 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
205a0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
205b0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
205c0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
205d0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
205e0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
205f0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
20600 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
20610 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
20620 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
20630 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
20640 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
20650 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
20660 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
20670 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
20680 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20690 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
206a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
206b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
206c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
206d0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
206e0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
206f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
20700 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
20710 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
20720 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
20730 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
20740 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
20750 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
20760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20770 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20780 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
20790 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
207a0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
207b0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
207c0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
207d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
207e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
207f0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
20800 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
20810 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
20820 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
20830 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
20840 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
20850 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
20860 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
20870 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
20880 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
20890 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
208a0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
208b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
208c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
208d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
208e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
208f0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
20900 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
20910 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
20920 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
20930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20940 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
20950 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
20960 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
20970 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
20980 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
20990 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
209a0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
209b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
209c0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
209d0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
209e0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
209f0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
20a00 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
20a10 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
20a20 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
20a30 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
20a40 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
20a50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
20a60 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
20a70 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
20a80 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
20a90 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
20aa0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
20ab0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
20ac0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
20ad0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
20ae0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
20af0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
20b00 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
20b10 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
20b20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
20b30 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
20b40 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
20b50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
20b60 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
20b70 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
20b80 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
20b90 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
20ba0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
20bb0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
20bc0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
20bd0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
20be0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
20bf0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
20c00 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
20c10 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
20c20 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
20c30 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
20c40 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
20c50 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
20c60 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
20c70 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
20c80 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
20c90 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
20ca0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
20cb0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
20cc0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
20cd0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
20ce0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
20cf0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
20d00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
20d10 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
20d20 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
20d30 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
20d40 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
20d50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
20d60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
20d70 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
20d80 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
20d90 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
20da0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
20db0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
20dc0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
20dd0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
20de0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
20df0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
20e00 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
20e10 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
20e20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
20e30 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
20e40 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
20e50 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
20e60 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
20e70 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
20e80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
20e90 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
20ea0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
20eb0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
20ec0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
20ed0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
20ee0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
20ef0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
20f00 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
20f10 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
20f20 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
20f30 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
20f40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20f50 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
20f60 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
20f70 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
20f80 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
20f90 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
20fa0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
20fb0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
20fc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
20fd0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
20fe0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
20ff0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
21000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21010 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
21020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21030 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
21040 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
21050 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
21060 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
21070 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
21080 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
21090 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
210a0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
210b0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
210c0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
210d0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
210e0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
210f0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
21100 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21110 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
21120 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
21130 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
21140 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
21150 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
21160 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
21170 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
21180 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
21190 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
211a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
211b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
211c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
211d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
211e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
211f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
21200 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
21210 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
21220 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
21230 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
21240 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
21250 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
21260 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
21270 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
21280 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
21290 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
212a0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
212b0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
212c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
212d0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
212e0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
212f0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
21300 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
21310 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
21320 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
21330 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
21340 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
21350 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
21360 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
21370 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
21380 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
21390 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
213a0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
213b0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
213c0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
213d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
213e0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
213f0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
21400 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
21410 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
21420 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21430 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21440 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
21450 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
21460 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
21470 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
21480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21490 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
214a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
214b0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
214c0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
214d0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
214e0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
214f0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
21500 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21510 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
21520 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
21530 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
21540 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
21550 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
21560 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
21570 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
21580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
21590 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 20 6e  a_count(P) the n
215a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
215b0 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68   in the.** of th
215c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
215d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
215e0 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] P..*/.int s
215f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
21600 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
21610 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
21620 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
21630 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
21640 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
21650 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
21660 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
21670 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
21680 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
21690 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
216a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
216b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
216c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
216d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
216e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
216f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
21700 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
21710 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
21720 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
21730 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
21740 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
21750 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
21760 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
21770 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
21780 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
21790 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
217a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
217b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
217c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
217d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
217e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
217f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
21800 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
21810 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
21820 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
21830 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
21840 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
21850 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
21860 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
21870 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
21880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
21890 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
218a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
218b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
218c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
218d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
218e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
218f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
21900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
21910 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
21920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
21930 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
21940 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
21950 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
21960 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
21970 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
21980 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
21990 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
219a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
219b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
219c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
219d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
219e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
219f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
21a00 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
21a10 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
21a20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21a30 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
21a40 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
21a50 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
21a60 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
21a70 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
21a80 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
21a90 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
21aa0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
21ab0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
21ac0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
21ad0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
21ae0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
21af0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
21b00 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
21b10 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
21b20 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
21b30 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
21b40 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
21b50 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
21b60 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
21b70 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
21b80 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
21b90 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
21ba0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
21bb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21bc0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
21bd0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
21be0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
21bf0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
21c00 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
21c10 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
21c20 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
21c30 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
21c40 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
21c50 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
21c60 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
21c70 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
21c80 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
21c90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
21ca0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
21cb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
21cc0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
21cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21ce0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
21cf0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
21d00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
21d10 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
21d20 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
21d30 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
21d40 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
21d50 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
21d60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21d70 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
21d80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
21d90 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
21da0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
21db0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
21dc0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
21dd0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
21de0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
21df0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21e00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
21e10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21e20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
21e30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
21e40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
21e50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21e60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
21e70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
21e80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
21e90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
21ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
21eb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
21ec0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
21ed0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
21ee0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
21ef0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
21f00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
21f10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
21f20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
21f30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
21f40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
21f50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
21f60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
21f70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
21f80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
21f90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
21fa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
21fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
21fc0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
21fd0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
21fe0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
21ff0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
22000 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
22010 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
22020 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
22030 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
22040 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
22050 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
22060 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
22070 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
22080 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
22090 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
220a0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
220b0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
220c0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
220d0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
220e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
220f0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
22100 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
22110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22120 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
22130 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
22140 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
22150 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
22160 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
22170 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
22180 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
22190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
221a0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
221b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
221c0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
221d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
221e0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
221f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
22200 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
22210 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
22220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
22230 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
22240 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
22250 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
22260 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
22270 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
22280 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
22290 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
222a0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76  tring..** ^The v
222b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
222c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
222d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
222e0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
222f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
22300 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
22310 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
22320 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
22330 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
22340 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
22350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
22360 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
22370 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
22380 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22390 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
223a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
223b0 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
223c0 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
223d0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
223e0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
223f0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
22400 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
22410 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
22420 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
22430 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
22440 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
22450 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
22460 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
22470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
22480 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
22490 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
224a0 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
224b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
224c0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
224d0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
224e0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
224f0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
22500 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a  UTF-8..** ^The z
22510 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
22520 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
22530 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
22540 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
22550 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
22560 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
22570 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
22580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22590 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
225a0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
225b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
225c0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
225d0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
225e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
225f0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
22600 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
22610 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
22620 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
22640 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
22650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22660 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
22670 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
22680 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
22690 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
226a0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
226b0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
226c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
226d0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
226e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
226f0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
22700 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
22710 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
22720 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
22730 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
22740 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
22750 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
22760 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
22770 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
22780 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
22790 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
227a0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
227b0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
227c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
227d0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
227e0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
227f0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
22800 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
22810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
22820 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
22830 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
22840 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
22850 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
22860 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
22870 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
22880 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
22890 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
228a0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
228b0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
228c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
228d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
228e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
228f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
22900 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
22910 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
22920 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
22930 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
22940 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
22950 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
22960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
22970 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
22980 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
22990 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
229a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
229b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
229c0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
229d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
229e0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
229f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
22a00 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
22a10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
22a20 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
22a30 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
22a40 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
22a50 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
22a60 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
22a70 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
22a80 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
22a90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
22aa0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
22ab0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
22ac0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
22ad0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
22ae0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
22af0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
22b00 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
22b10 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
22b20 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
22b30 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
22b40 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
22b50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
22b60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
22b70 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
22b80 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
22b90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
22ba0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
22bb0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
22bc0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
22bd0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
22be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
22bf0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
22c00 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
22c10 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
22c20 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
22c30 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
22c40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
22c50 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
22c60 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
22c70 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
22c80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
22c90 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
22ca0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22cb0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
22cc0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
22cd0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
22ce0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
22cf0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
22d00 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
22d10 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
22d20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
22d30 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
22d40 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
22d50 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
22d60 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
22d70 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
22d80 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
22d90 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
22da0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
22db0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
22dc0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
22dd0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
22de0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
22df0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
22e00 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
22e10 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 77  .** ^Note that w
22e20 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
22e30 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
22e40 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
22e50 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
22e60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
22e70 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
22e80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
22e90 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
22ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22eb0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
22ec0 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65  dated..** ^(Type
22ed0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
22ee0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
22ef0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
22f00 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
22f10 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
22f20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
22f30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
22f40 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
22f50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22f60 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
22f70 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
22f80 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
22f90 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
22fa0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
22fb0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
22fc0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
22fd0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
22fe0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
22ff0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
23000 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
23010 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23020 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
23030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23040 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
23050 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
23060 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23070 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
23080 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
23090 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
230a0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
230b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
230c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
230d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
230e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
230f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
23100 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
23110 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
23120 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
23130 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
23140 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
23150 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
23160 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
23170 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
23180 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
23190 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
231a0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
231b0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
231c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
231d0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
231e0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
231f0 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
23200 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
23210 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
23220 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
23230 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
23240 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
23250 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
23260 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
23270 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
23280 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
23290 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
232a0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
232b0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dated..**.** ^(T
232c0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
232d0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
232e0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
232f0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
23300 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
23310 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
23320 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
23330 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
23340 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
23350 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
23360 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23370 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
23380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23390 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
233a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
233b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
233c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
233d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
233e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
23400 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29  )</li>.** </ul>)
23410 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ^.**.** In other
23420 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
23430 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
23440 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
23450 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
23460 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
23470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23480 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
23490 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
234a0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
234b0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
234c0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
234d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
234e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
234f0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
23500 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
23510 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
23520 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
23530 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
23540 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
23550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23560 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
23570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23580 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
23590 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
235a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
235b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
235c0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
235d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
235e0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
235f0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
23600 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
23610 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
23620 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
23630 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
23640 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
23650 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
23660 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23670 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
23680 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
23690 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
236a0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
236b0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
236c0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
236d0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
236e0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
236f0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
23700 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
23710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23720 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
23730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23740 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
23750 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
23760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
23770 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
23780 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
23790 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
237a0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
237b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
237c0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
237d0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
237e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
237f0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
23800 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
23810 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
23820 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
23830 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
23840 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
23850 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
23860 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
23870 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
23880 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
23890 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
238a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
238b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
238c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
238d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
238e0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
238f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
23900 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
23910 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
23920 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
23930 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
23940 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
23950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23960 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
23970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
23980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23990 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
239a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
239b0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
239c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
239d0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
239e0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
239f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23a00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23a10 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
23a20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23a30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
23a40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23a50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
23a60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
23a70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23a80 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
23a90 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
23aa0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
23ab0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23ac0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
23ad0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
23ae0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
23af0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
23b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
23b10 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
23b20 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
23b30 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
23b40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
23b50 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d  * ^If the statem
23b60 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64  ent was executed
23b70 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72   successfully or
23b80 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74   not executed at
23b90 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51   all, then.** SQ
23ba0 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
23bb0 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 74 69  ned. ^If executi
23bc0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
23bd0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
23be0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
23bf0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
23c00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23c10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
23c20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
23c30 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
23c40 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
23c50 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
23c60 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23c70 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
23c80 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
23c90 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a  chine has not.**
23ca0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
23cb0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
23cc0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
23cd0 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
23ce0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
23cf0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73  n error or an [s
23d00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
23d10 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a   | interrupt]..*
23d20 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  * ^Incomplete up
23d30 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
23d40 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
23d50 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
23d60 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
23d70 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
23d80 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
23d90 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
23da0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
23db0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
23dc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
23dd0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
23de0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
23e00 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
23e10 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
23e20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23e30 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
23e40 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
23e50 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
23e60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
23e70 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
23e80 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
23e90 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
23ea0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
23eb0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
23ec0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
23ed0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
23ee0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
23ef0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
23f00 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
23f10 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
23f20 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
23f30 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
23f40 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
23f50 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
23f60 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
23f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
23f80 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
23f90 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
23fa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23fb0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
23fc0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
23fd0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
23fe0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
23ff0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
24000 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
24010 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
24020 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24030 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
24040 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
24050 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
24060 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
24070 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
24080 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
24090 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
240a0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
240b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
240c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
240d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
240e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
240f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
24100 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
24110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24120 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
24130 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
24140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24150 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
24160 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
24170 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
24180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
24190 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
241a0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
241b0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
241c0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
241d0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
241e0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
241f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24200 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24210 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
24220 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
24230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
24240 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
24250 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
24260 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
24270 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
24280 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
24290 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
242a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
242b0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
242c0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
242d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
242e0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
242f0 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74  ^These two funct
24300 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
24310 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
24320 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
24330 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
24340 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
24350 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
24360 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
24370 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
24380 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
24390 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
243a0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
243b0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
243c0 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
243d0 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
243e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
243f0 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
24400 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
24410 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
24420 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
24430 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
24440 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24450 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
24460 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
24470 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24480 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
24490 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
244a0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
244b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
244c0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
244d0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
244e0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
244f0 5e 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  ^If a single pro
24500 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
24510 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
24520 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
24530 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
24540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
24550 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
24560 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
24570 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
24580 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
24590 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
245a0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
245b0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
245c0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
245d0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
245e0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
245f0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
24600 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
24610 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
24620 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65  f.** the zero-te
24630 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
24640 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
24650 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
24660 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
24670 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79  haracters.  ^Any
24680 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
24690 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
246a0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
246b0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
246c0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
246d0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
246e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
246f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
24700 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
24710 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
24720 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
24730 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
24740 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
24750 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
24760 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
24770 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24780 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
24790 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
247a0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
247b0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
247c0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
247d0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
247e0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
247f0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
24800 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
24810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
24820 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
24830 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
24840 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24850 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
24860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
24870 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
24880 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
24890 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
248a0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
248b0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
248c0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
248d0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
248e0 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
248f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
24900 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
24910 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
24920 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
24930 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
24940 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
24950 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
24960 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
24970 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
24980 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
24990 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
249a0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
249b0 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
249c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
249d0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
249e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
249f0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
24a00 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
24a10 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
24a20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
24a30 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
24a40 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
24a50 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
24a60 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
24a70 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
24a80 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
24a90 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
24aa0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
24ab0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
24ac0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
24ad0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
24ae0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
24af0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
24b00 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
24b10 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
24b20 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
24b30 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
24b40 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
24b50 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
24b60 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
24b70 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
24b80 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
24b90 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
24ba0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
24bb0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
24bc0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
24bd0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
24be0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
24bf0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
24c00 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].)^.**.** The
24c10 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
24c20 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
24c30 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
24c40 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
24c50 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
24c60 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
24c70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
24c80 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
24c90 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
24ca0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
24cb0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
24cc0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
24cd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
24ce0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
24cf0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
24d00 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
24d10 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
24d20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
24d30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
24d40 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
24d50 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
24d60 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
24d70 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
24d80 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
24d90 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
24da0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
24db0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
24dc0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
24dd0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
24de0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
24df0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
24e00 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
24e10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  s..**.** ^It is 
24e20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
24e30 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
24e40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
24e50 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
24e60 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
24e70 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
24e80 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
24e90 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
24ea0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
24eb0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
24ec0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
24ed0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
24ee0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
24ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
24f00 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
24f10 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
24f20 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
24f30 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
24f40 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
24f50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24f60 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
24f70 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
24f80 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
24f90 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
24fa0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
24fb0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
24fc0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
24fd0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
24fe0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
24ff0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
25000 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
25010 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
25020 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
25030 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
25040 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
25050 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
25060 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
25070 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
25080 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
25090 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
250a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
250b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
250c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
250d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
250e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
250f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
25100 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
25110 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
25120 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
25130 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
25140 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
25150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
25160 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66  tions..** ^The f
25170 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
25180 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25190 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
251a0 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
251b0 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
251c0 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
251d0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
251e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
251f0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
25200 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70   ^Subsequent app
25210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25220 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68   functions of th
25230 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79  e same name only
25240 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72   override .** pr
25250 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ior application-
25260 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25270 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78  s that are an ex
25280 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68  act match for th
25290 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70  e.** number of p
252a0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72  arameters and pr
252b0 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67  eferred encoding
252c0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
252d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
252e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
252f0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
25300 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
25310 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
25320 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
25330 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
25340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25350 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
25360 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
25370 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
25380 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
25390 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
253a0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
253b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
253c0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
253d0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
253e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
253f0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
25400 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
25410 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
25420 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
25430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25440 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25450 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25460 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
25470 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25480 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25490 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
254a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
254b0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
254c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
254d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
254e0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
254f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
25500 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
25510 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
25520 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
25530 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
25540 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
25550 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
25560 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
25570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25580 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25590 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
255a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
255b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
255c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
255d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
255e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
255f0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
25600 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
25610 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
25620 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
25630 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
25640 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
25650 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
25660 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
25670 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
25680 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
25690 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
256a0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
256b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
256c0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
256d0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
256e0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
256f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
25700 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
25710 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
25720 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
25730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25740 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
25750 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
25760 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
25770 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
25780 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
25790 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
257a0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
257b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
257c0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
257d0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
257e0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
257f0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
25800 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
25810 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
25820 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
25830 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
25840 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
25850 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
25860 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
25870 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
25880 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
25890 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
258a0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
258b0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
258c0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
258d0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
258e0 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
258f0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
25900 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
25910 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
25920 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
25930 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
25940 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
25950 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
25960 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
25970 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
25980 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
25990 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
259a0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
259b0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
259c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
259d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
259e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
259f0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
25a00 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
25a10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
25a20 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
25a30 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
25a40 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
25a50 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
25a60 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
25a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
25a80 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
25a90 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
25aa0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
25ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
25ac0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
25ad0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
25ae0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
25af0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
25b00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
25b10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
25b20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
25b30 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
25b40 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
25b50 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
25b60 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
25b70 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
25b80 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
25b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
25ba0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
25bb0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
25bc0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
25bd0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
25be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
25bf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
25c00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
25c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
25c20 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
25c30 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
25c40 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
25c50 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
25c60 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
25c70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
25c80 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
25c90 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
25ca0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
25cb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25cc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
25cd0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
25ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25cf0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
25d00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
25d10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
25d20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25d30 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
25d40 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
25d50 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
25d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
25d70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25d80 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
25d90 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
25da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25db0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
25dc0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
25dd0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
25de0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
25df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
25e00 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
25e10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
25e20 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
25e30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
25e40 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
25e50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
25e60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
25e70 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
25e80 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
25e90 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
25ea0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
25eb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25ec0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
25ed0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
25ee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
25ef0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
25f00 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
25f10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
25f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25f30 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
25f40 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
25f50 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
25f60 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
25f70 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
25f80 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
25f90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
25fa0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
25fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25fc0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
25fd0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
25fe0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
25ff0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
26000 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
26010 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
26020 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
26030 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
26040 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
26050 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
26060 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
26070 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
26080 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
26090 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
260a0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
260b0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
260c0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
260d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
260e0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
260f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
26100 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
26110 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
26120 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
26130 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
26140 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
26150 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
26160 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
26170 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
26180 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
26190 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
261a0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
261b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
261c0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
261d0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
261e0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
261f0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
26200 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
26210 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
26220 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
26230 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
26240 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
26250 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
26260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26270 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
26280 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26290 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
262a0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
262b0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
262c0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
262d0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
262e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
262f0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
26300 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
26310 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
26320 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
26330 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26340 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
26350 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
26360 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
26370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
26380 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
26390 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
263a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
263b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
263c0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
263d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
263e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
263f0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
26400 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
26410 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
26420 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
26430 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
26440 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
26450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
26470 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
26480 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
26490 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
264a0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
264b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
264c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
264d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
264e0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
264f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
26500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26510 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
26520 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
26530 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
26540 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
26550 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
26560 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
26570 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
26580 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
26590 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
265a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
265b0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
265c0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
265d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
265e0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
265f0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
26600 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
26610 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
26620 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20  mplementions of 
26630 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
26640 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
26650 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
26660 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
26670 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
26680 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
26690 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
266a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
266b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
266c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
266d0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
266e0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
266f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
26700 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
26710 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
26720 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
26730 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
26740 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
26750 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
26760 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
26770 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
26780 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
26790 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
267a0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
267b0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
267c0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
267d0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
267e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
267f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
26800 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
26810 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
26820 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
26830 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
26840 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
26850 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
26860 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
26870 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
26880 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
26890 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
268a0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
268b0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
268c0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
268d0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
268e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
268f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
26900 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
26910 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
26920 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
26930 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
26940 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
26950 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
26960 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
26970 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
26980 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
26990 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
269a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
269b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
269c0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
269d0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
269e0 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
269f0 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
26a00 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
26a10 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
26a20 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
26a30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
26a40 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
26a50 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
26a60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26a70 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
26a80 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
26a90 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
26aa0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
26ab0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
26ac0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
26ad0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
26ae0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
26af0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26b00 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
26b10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
26b20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
26b30 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
26b40 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
26b50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
26b60 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
26b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
26b80 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
26b90 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
26ba0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26bb0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
26bc0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
26bd0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
26be0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
26bf0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
26c00 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
26c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
26c20 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
26c30 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
26c40 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
26c50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
26c60 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
26c70 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
26c80 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
26c90 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
26ca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
26cb0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
26cc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
26cd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
26ce0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
26cf0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
26d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
26d10 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
26d20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
26d30 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
26d40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
26d50 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
26d60 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
26d70 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
26d80 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
26d90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
26da0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26db0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
26dc0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
26dd0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
26de0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
26df0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
26e00 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
26e10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26e20 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
26e30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26e40 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
26e50 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
26e60 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
26e70 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
26e80 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
26e90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
26ea0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
26eb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
26ec0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
26ed0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
26ee0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26ef0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
26f00 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
26f10 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
26f20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26f30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
26f40 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
26f50 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
26f60 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
26f70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
26f80 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
26f90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26fa0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
26fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
26fc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26fd0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
26fe0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
26ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
27000 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
27010 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
27020 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
27030 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
27040 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
27050 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
27060 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
27070 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
27080 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
27090 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
270a0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
270b0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
270c0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
270d0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
270e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
270f0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
27100 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
27110 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
27120 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
27130 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
27140 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
27150 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
27160 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
27170 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
27180 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
27190 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
271a0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
271b0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
271c0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
271d0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
271e0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
271f0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
27200 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
27210 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
27220 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
27230 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
27240 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
27250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
27260 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
27270 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
27280 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
27290 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
272a0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
272b0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
272c0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
272d0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
272e0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
272f0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
27300 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
27310 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
27320 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
27330 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
27340 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
27350 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
27360 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
27370 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
27380 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
27390 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
273a0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
273b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
273c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
273d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
273e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
273f0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
27400 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
27410 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27420 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
27430 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
27440 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
27450 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
27460 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
27470 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
27480 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
27490 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
274a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
274b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
274c0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
274d0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
274e0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
274f0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
27500 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
27510 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
27520 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
27530 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
27540 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
27550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
27560 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
27570 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
27580 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
27590 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
275a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
275b0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
275c0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
275d0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
275e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
275f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
27600 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
27610 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
27620 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
27630 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
27640 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
27650 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
27660 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
27670 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
27680 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
27690 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
276a0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
276b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
276c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
276d0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
276e0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
276f0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
27700 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
27710 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
27720 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
27730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
27740 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
27750 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
27760 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
27770 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
27780 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
27790 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
277a0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
277b0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
277c0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
277d0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
277e0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
277f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
27800 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
27810 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
27820 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
27830 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
27840 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
27850 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
27860 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
27870 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
27880 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
27890 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
278a0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
278b0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
278c0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
278d0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
278e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
278f0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
27900 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
27910 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
27920 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
27930 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
27940 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
27950 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
27960 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
27970 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
27980 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
27990 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
279a0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
279b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
279c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
279d0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
279e0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
279f0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
27a00 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
27a10 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
27a20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
27a30 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
27a40 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
27a50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
27a60 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
27a70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
27a80 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
27a90 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
27aa0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
27ab0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
27ac0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
27ad0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
27ae0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
27af0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
27b00 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
27b10 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
27b20 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
27b30 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
27b40 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
27b50 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
27b60 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
27b70 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
27b80 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
27b90 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
27ba0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
27bb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
27bc0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
27bd0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
27be0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
27bf0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
27c00 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
27c10 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
27c20 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
27c30 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
27c40 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
27c50 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
27c60 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
27c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
27c80 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
27c90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
27ca0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
27cb0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
27cc0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
27cd0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
27ce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27cf0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
27d00 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
27d10 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
27d20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
27d30 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
27d40 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
27d50 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
27d60 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
27d70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
27d80 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
27d90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27da0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
27db0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27dc0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
27dd0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
27de0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
27df0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
27e00 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
27e10 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
27e20 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
27e30 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
27e40 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
27e50 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
27e60 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
27e70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e80 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
27e90 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
27ea0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
27eb0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
27ec0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
27ed0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27ee0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
27ef0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
27f00 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
27f10 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
27f20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27f30 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
27f40 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
27f50 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
27f60 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
27f70 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
27f80 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
27f90 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
27fa0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
27fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
27fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
27fd0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
27fe0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
27ff0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
28000 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28010 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
28020 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
28030 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
28040 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
28050 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
28060 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
28070 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
28080 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
28090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
280a0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
280b0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
280c0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
280d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
280e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
280f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28100 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
28110 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
28120 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
28130 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28140 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
28150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28160 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
28170 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
28180 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
28190 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
281a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
281b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
281c0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
281d0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
281e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
281f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28200 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
28210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28220 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
28230 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
28240 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
28250 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
28260 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
28270 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
28280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
28290 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
282a0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
282b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
282c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
282d0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
282e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
282f0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
28300 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
28310 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28320 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28330 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
28340 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28350 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
28360 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
28370 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
28380 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
28390 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
283a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
283b0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
283c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
283d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
283e0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
283f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28400 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
28410 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
28420 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
28430 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
28440 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
28450 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
28460 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
28470 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
28480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28490 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
284a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
284b0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
284c0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
284d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
284e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
284f0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
28500 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
28510 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
28520 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
28530 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
28540 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
28550 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
28560 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
28570 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28580 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
28590 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
285a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
285b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
285c0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
285d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
285e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
285f0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
28600 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
28610 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
28620 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
28630 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
28640 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
28650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28660 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
28670 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
28680 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
28690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
286a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
286b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
286c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
286d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
286e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
286f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
28700 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72   is to long to r
28710 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
28720 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
28730 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
28740 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
28750 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
28760 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
28770 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
28780 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
28790 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
287a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
287b0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
287c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
287d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
287e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
287f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28800 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
28810 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
28820 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
28830 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
28840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28850 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
28860 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28870 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
28880 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
28890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
288a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
288b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
288c0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
288d0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
288e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
288f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
28900 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
28910 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
28920 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
28930 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28940 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
28950 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
28960 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28970 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
28980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28990 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
289a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
289b0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
289c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
289d0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
289e0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
289f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
28a00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28a10 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28a20 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
28a30 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
28a40 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
28a50 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
28a60 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
28a70 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
28a80 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
28a90 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
28aa0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
28ab0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
28ac0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
28ad0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
28ae0 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
28af0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
28b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28b10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
28b20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
28b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
28b40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28b50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
28b60 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
28b70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
28b80 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
28b90 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
28ba0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
28bb0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28bc0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
28bd0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
28be0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
28bf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
28c00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
28c10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
28c20 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
28c30 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
28c40 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
28c50 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
28c60 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
28c70 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
28c80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28c90 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
28ca0 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
28cb0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
28cc0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
28cd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
28ce0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
28cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28d00 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
28d10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
28d20 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
28d30 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
28d40 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
28d50 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
28d60 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
28d70 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
28d80 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
28d90 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
28da0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28db0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28dc0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
28dd0 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
28de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
28df0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
28e00 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
28e10 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
28e20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
28e30 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
28e40 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
28e50 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
28e60 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
28e70 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
28e80 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
28e90 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
28ea0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
28eb0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
28ec0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
28ed0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
28ee0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
28ef0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
28f00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
28f10 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
28f20 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
28f30 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
28f40 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
28f50 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
28f60 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
28f70 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
28f80 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
28f90 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
28fa0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
28fb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
28fc0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
28fd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
28fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
28ff0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
29000 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29010 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
29020 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29030 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29040 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
29050 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
29060 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29070 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
29080 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
29090 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
290a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
290b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
290c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
290d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
290e0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
290f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
29100 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
29110 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
29120 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
29130 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
29140 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29150 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
29160 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
29170 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
29180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29190 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
291a0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
291b0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
291c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
291d0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
291e0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
291f0 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
29200 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29210 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
29220 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
29230 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
29240 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29250 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
29260 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
29270 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
29280 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
29290 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
292a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
292b0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
292c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
292d0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
292e0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
292f0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
29300 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29310 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
29320 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
29330 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
29340 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
29350 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29360 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
29370 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
29380 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
29390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
293a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
293b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
293c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
293d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
293e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
293f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29400 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
29410 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
29420 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
29430 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
29440 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29450 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
29460 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
29470 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29480 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
29490 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
294a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
294b0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
294c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
294d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
294e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
294f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
29500 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
29510 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29520 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
29530 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
29540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29550 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
29560 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
29570 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
29580 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
29590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
295a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
295b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
295c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
295d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
295e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
295f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
29600 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
29610 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
29620 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
29630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29640 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
29650 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
29660 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
29670 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
29680 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
29690 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
296a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
296b0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
296c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
296d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
296e0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
296f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29700 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
29710 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
29720 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
29730 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
29740 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
29750 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
29760 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
29770 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
29780 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
29790 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
297a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
297b0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
297c0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
297d0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
297e0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
297f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29800 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
29810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29820 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
29830 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
29840 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
29850 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29860 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63  n16(). ^In all c
29870 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
29880 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
29890 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
298a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
298b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
298c0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
298d0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
298e0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
298f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
29900 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6LE], or [SQLITE
29910 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
29920 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
29930 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
29940 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
29950 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
29960 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
29970 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
29980 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
29990 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
299a0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
299b0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
299c0 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64  y. ^The.** third
299d0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
299e0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
299f0 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
29a00 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
29a10 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
29a20 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
29a30 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
29a40 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
29a50 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
29a60 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
29a70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
29a80 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
29a90 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
29aa0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
29ab0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
29ac0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
29ad0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
29ae0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
29af0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
29b00 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
29b10 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
29b20 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
29b30 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
29b40 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
29b50 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
29b60 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
29b70 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
29b80 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
29b90 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
29ba0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
29bb0 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e  t anymore)..** ^
29bc0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
29bd0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
29be0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
29bf0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
29c00 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
29c10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
29c20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
29c30 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
29c40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
29c50 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
29c60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
29c70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
29c80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
29c90 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  )..**.** ^The re
29ca0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
29cb0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
29cc0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
29cd0 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
29ce0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
29cf0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
29d00 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
29d10 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
29d20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
29d30 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
29d40 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
29d50 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
29d60 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
29d70 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
29d80 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70  stered.  The app
29d90 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
29da0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
29db0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
29dc0 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
29dd0 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
29de0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
29df0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
29e00 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
29e10 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
29e20 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
29e30 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
29e40 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
29e50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
29e60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
29e70 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
29e80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29e90 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
29ea0 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
29eb0 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
29ec0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
29ed0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
29ee0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
29ef0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
29f00 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
29f10 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
29f20 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
29f30 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
29f40 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
29f50 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
29f60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
29f70 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
29f80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
29f90 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73  ..** ^Collations
29fa0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
29fb0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
29fc0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
29fd0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
29fe0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
29ff0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2a000 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
2a010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a020 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
2a030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2a040 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
2a050 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
2a060 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2a070 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a080 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a090 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
2a0a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a0b0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2a0c0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2a0d0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2a0e0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2a0f0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2a100 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2a110 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2a120 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2a130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2a140 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2a150 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2a160 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2a170 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2a180 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2a190 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2a1a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2a1b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2a1c0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
2a1d0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2a1e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a1f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2a200 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2a210 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2a220 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
2a230 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2a240 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2a250 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2a260 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2a270 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2a280 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2a290 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2a2a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2a2b0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2a2c0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2a2d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2a2e0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2a2f0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2a300 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2a310 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2a320 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2a330 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2a340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a350 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2a360 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2a370 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2a380 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2a390 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2a3a0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2a3b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2a3c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a3d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a3e0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2a3f0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2a400 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2a410 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2a420 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2a430 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2a440 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2a450 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2a460 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2a470 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2a480 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2a490 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2a4a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2a4b0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2a4c0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2a4d0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2a4e0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2a4f0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2a500 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2a510 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2a520 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2a530 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2a540 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2a550 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2a560 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2a570 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a580 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2a590 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2a5a0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2a5b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a5c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2a5d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2a5e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2a5f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2a600 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2a610 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2a620 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2a630 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2a640 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2a650 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2a660 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2a670 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2a680 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2a690 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2a6a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2a6b0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2a6c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2a6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2a6e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2a6f0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2a700 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2a710 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2a720 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a730 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2a740 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2a750 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2a760 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a770 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2a780 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a790 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2a7a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2a7b0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2a7c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2a7d0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2a7e0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2a7f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2a800 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2a810 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2a820 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2a830 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2a840 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2a850 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2a860 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
2a870 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
2a880 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
2a890 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
2a8a0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
2a8b0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
2a8c0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
2a8d0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2a8e0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2a8f0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2a900 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2a910 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2a920 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2a930 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
2a940 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a950 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a960 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2a970 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2a980 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2a990 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
2a9a0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2a9b0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
2a9c0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
2a9d0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
2a9e0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
2a9f0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
2aa00 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
2aa10 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
2aa20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
2aa30 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
2aa40 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
2aa50 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
2aa60 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2aa70 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2aa80 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2aa90 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2aaa0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2aab0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2aac0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
2aad0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2aae0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2aaf0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2ab00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2ab10 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2ab20 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
2ab30 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2ab40 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
2ab50 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2ab60 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
2ab70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ab80 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2ab90 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2aba0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2abb0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2abc0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2abd0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2abe0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2abf0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2ac00 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eter..**.** ^If 
2ac10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2ac20 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
2ac30 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
2ac40 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
2ac50 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
2ac60 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
2ac70 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
2ac80 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
2ac90 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
2aca0 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72  ond. ^The number
2acb0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2acc0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2acd0 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
2ace0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
2acf0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
2ad00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
2ad10 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
2ad20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
2ad30 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
2ad40 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
2ad50 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2ad60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
2ad70 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ject..*/.int sql
2ad80 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2ad90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ada0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2adb0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2adc0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2add0 2a 2a 20 5e 49 66 20 74 68 69 73 20 67 6c 6f 62  ** ^If this glob
2ade0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
2adf0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2ae00 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
2ae10 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2ae20 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
2ae30 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
2ae40 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
2ae50 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
2ae60 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
2ae70 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
2ae80 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
2ae90 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
2aea0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
2aeb0 64 69 72 65 63 74 6f 72 79 2e 20 20 5e 49 66 20  directory.  ^If 
2aec0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2aed0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2aee0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2aef0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2af00 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2af10 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2af20 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2af30 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2af40 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2af50 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2af60 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2af70 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2af80 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2af90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2afa0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2afb0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2afc0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2afd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2afe0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2aff0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2b000 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2b010 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2b020 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2b030 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2b040 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2b050 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2b060 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2b070 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2b080 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2b090 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2b0a0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2b0b0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2b0c0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2b0d0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2b0e0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2b0f0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2b100 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2b110 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2b120 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2b130 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2b140 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2b150 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2b160 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2b170 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2b180 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2b190 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2b1a0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2b1b0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2b1c0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2b1d0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2b1e0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2b1f0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2b200 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2b210 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2b220 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2b230 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2b240 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2b250 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2b260 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2b270 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2b280 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2b290 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2b2a0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2b2b0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2b2c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2b2d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2b2e0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2b2f0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2b300 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2b310 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2b320 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2b330 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2b340 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2b350 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2b360 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2b370 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2b380 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2b390 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2b3a0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2b3b0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2b3c0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2b3d0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2b3e0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2b3f0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2b400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b410 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2b420 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2b430 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2b440 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2b450 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2b460 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2b470 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2b480 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2b490 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2b4a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2b4b0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2b4c0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2b4d0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2b4e0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2b4f0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2b500 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2b510 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2b520 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2b530 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2b540 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2b550 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2b560 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2b570 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2b580 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2b590 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2b5a0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2b5b0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2b5c0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2b5d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2b5e0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2b5f0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2b600 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2b610 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2b620 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2b630 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2b640 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2b650 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2b660 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2b670 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2b680 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2b690 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2b6a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2b6b0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2b6c0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2b6d0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2b6e0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2b6f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2b700 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2b710 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2b720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b730 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2b740 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2b750 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b760 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2b770 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2b780 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2b790 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2b7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2b7b0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2b7c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b7d0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2b7e0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2b7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2b800 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2b810 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2b820 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2b830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2b840 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2b850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2b860 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2b870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b880 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2b890 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2b8a0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2b8b0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2b8c0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2b8d0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2b8e0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2b8f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2b900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b910 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2b920 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b930 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2b940 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b950 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2b960 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2b970 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2b980 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2b990 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2b9a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b9b0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2b9c0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2b9d0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2b9e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2b9f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2ba00 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2ba10 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2ba20 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2ba30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ba40 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2ba50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ba60 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2ba70 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2ba80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2ba90 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2baa0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2bab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2bac0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2bad0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2bae0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2baf0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2bb00 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2bb10 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2bb20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2bb30 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2bb40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2bb50 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2bb60 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2bb70 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2bb80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bb90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bba0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2bbb0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2bbc0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2bbd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bbe0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2bbf0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2bc00 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2bc10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2bc20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2bc30 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2bc40 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2bc50 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2bc60 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2bc70 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2bc80 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2bc90 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2bca0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2bcb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2bcc0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2bcd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2bce0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2bcf0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2bd00 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2bd10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2bd20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2bd30 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2bd40 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2bd50 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2bd60 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2bd70 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2bd80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2bd90 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2bda0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2bdb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bdc0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2bdd0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2bde0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2bdf0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2be00 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2be10 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2be20 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2be30 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2be40 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2be50 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2be60 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2be70 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2be80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2be90 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2bea0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2beb0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2bec0 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2bed0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2bee0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2bef0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2bf00 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2bf10 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2bf20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bf30 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2bf40 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2bf50 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2bf60 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
2bf70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2bf80 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2bf90 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2bfa0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2bfb0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bfd0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2bfe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2bff0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2c000 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2c010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c020 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2c030 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2c040 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2c050 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2c060 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2c070 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2c080 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2c090 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2c0a0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2c0b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2c0c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c0d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2c0e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2c0f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2c100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2c110 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2c120 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2c130 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2c140 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
2c150 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
2c160 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
2c170 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2c180 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
2c190 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
2c1a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
2c1b0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
2c1c0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
2c1d0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
2c1e0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
2c1f0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
2c200 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2c210 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2c220 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2c230 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2c240 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
2c250 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
2c260 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2c270 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
2c280 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
2c290 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
2c2a0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
2c2b0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
2c2c0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
2c2d0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
2c2e0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
2c2f0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2c300 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2c310 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2c320 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2c330 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2c340 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2c350 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2c360 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2c370 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2c380 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2c390 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2c3a0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
2c3b0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2c3c0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2c3d0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2c3e0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2c3f0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2c400 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2c410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c420 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2c430 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2c440 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2c450 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2c460 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
2c470 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2c480 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
2c490 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
2c4a0 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65  n-zero..**.** Se
2c4b0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
2c4c0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2c4d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
2c4e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
2c4f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
2c500 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
2c510 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
2c520 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
2c530 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
2c540 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
2c550 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
2c560 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
2c570 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
2c580 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2c590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c5a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
2c5b0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2c5c0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
2c5d0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
2c5e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c5f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
2c600 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
2c610 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2c620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2c630 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
2c640 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2c650 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
2c660 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2c670 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2c680 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
2c690 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
2c6a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2c6b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
2c6c0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ridden..**.** ^T
2c6d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c6e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
2c6f0 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
2c700 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
2c710 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
2c720 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
2c730 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  deleted..** ^The
2c740 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2c750 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2c760 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2c770 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
2c780 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  ** to sqlite3_up
2c790 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
2c7a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ^The second call
2c7b0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2c7c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2c7d0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2c7e0 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
2c7f0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
2c800 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2c810 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2c820 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2c830 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
2c840 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74  voked..** ^The t
2c850 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2c860 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2c870 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
2c880 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
2c890 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
2c8a0 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
2c8b0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
2c8c0 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68  cted row..** ^Th
2c8d0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
2c8e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2c8f0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
2c900 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65   row..** ^In the
2c910 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
2c920 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
2c930 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68  [rowid] after th
2c940 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
2c950 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lace..**.** ^(Th
2c960 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
2c970 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
2c980 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
2c990 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
2c9a0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
2c9b0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
2c9c0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
2c9d0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ).)^.**.** ^In t
2c9e0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
2c9f0 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75  mentation, the u
2ca00 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73  pdate hook.** is
2ca10 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
2ca20 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f  n duplication ro
2ca30 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62  ws are deleted b
2ca40 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20  ecause of an.** 
2ca50 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f  [ON CONFLICT | O
2ca60 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41  N CONFLICT REPLA
2ca70 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f  CE] clause.  ^No
2ca80 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20  r is the update 
2ca90 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  hook.** invoked 
2caa0 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65  when rows are de
2cab0 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  leted using the 
2cac0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
2cad0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  zation]..** The 
2cae0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e  exceptions defin
2caf0 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  ed in this parag
2cb00 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67  raph might chang
2cb10 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
2cb20 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2cb30 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  te..**.** The up
2cb40 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d  date hook implem
2cb50 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2cb60 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2cb70 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2cb80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2cb90 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2cba0 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74  nvoked the updat
2cbb0 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74  e hook.  Any act
2cbc0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2cbd0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2cbe0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2cbf0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2cc00 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2cc10 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2cc20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2cc30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2cc40 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20  ered the update 
2cc50 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  hook..** Note th
2cc60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
2cc70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2cc80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
2cc90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
2cca0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2ccb0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
2ccc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
2ccd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
2cce0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54  agraph..**.** ^T
2ccf0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
2cd00 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  e_hook(D,C,P) fu
2cd10 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e  nction.** return
2cd20 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
2cd30 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2cd40 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68  us call.** on th
2cd50 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2cd60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
2cd70 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
2cd80 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e  he first call on
2cd90 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c   D..**.** See al
2cda0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
2cdb0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61  commit_hook()] a
2cdc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  nd [sqlite3_roll
2cdd0 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20  back_hook()].** 
2cde0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76  interfaces..*/.v
2cdf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
2ce00 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
2ce10 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
2ce20 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
2ce30 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
2ce40 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
2ce50 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
2ce60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ce70 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2ce80 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
2ce90 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f  r Cache.** KEYWO
2cea0 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63  RDS: {shared cac
2ceb0 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  he}.**.** ^(This
2cec0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
2ced0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
2cee0 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
2cef0 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
2cf00 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
2cf10 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
2cf20 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  ween [database c
2cf30 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e  onnection | conn
2cf40 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74  ections].** to t
2cf50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2cf60 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  . Sharing is ena
2cf70 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2cf80 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20  ment is true.** 
2cf90 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
2cfa0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2cfb0 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  false.)^.**.** ^
2cfc0 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
2cfd0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
2cfe0 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74  abled for an ent
2cff0 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20  ire process..** 
2d000 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
2d010 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
2d020 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20  rsion 3.5.0. In 
2d030 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f  prior versions o
2d040 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61  f SQLite,.** sha
2d050 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64  ring was enabled
2d060 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72   or disabled for
2d070 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70   each thread sep
2d080 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2d090 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69  (The cache shari
2d0a0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
2d0b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
2d0c0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
2d0d0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2d0e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2d0f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2d100 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
2d110 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
2d120 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
2d130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2d140 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
2d150 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
2d160 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
2d170 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
2d180 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
2d190 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
2d1a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2d1b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
2d1c0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
2d1d0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
2d1e0 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
2d1f0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
2d200 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2d210 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e  ned otherwise.)^
2d220 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63  .**.** ^Shared c
2d230 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
2d240 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
2d250 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
2d260 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
2d270 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2d280 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
2d290 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
2d2a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
2d2b0 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
2d2c0 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
2d2d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c  ly..**.** See Al
2d2e0 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61  so:  [SQLite Sha
2d2f0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a  red-Cache Mode].
2d300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2d310 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2d320 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
2d330 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
2d340 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
2d350 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  emory.**.** ^The
2d360 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2d370 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2d380 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2d390 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2d3a0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2d3b0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2d3c0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2d3d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2d3e0 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2d3f0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2d400 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74     Memory used t
2d410 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
2d420 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70  .** pages to imp
2d430 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
2d440 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
2d450 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  f non-essential 
2d460 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69  memory..** ^sqli
2d470 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2d480 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65  ry() returns the
2d490 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d4a0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
2d4b0 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20  .** which might 
2d4c0 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20  be more or less 
2d4d0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
2d4e0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e  requested..*/.in
2d4f0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
2d500 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
2d510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d520 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
2d530 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
2d540 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d550 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
2d560 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65   interface place
2d570 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
2d580 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  .** on the amoun
2d590 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
2d5a0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
2d5b0 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
2d5c0 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e 74 65  ..** ^If an inte
2d5d0 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
2d5e0 69 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61  is requested tha
2d5f0 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
2d600 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20  he.** soft heap 
2d610 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
2d620 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2d630 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  ] is invoked one
2d640 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65   or.** more time
2d650 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
2d660 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
2d670 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  he allocation is
2d680 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
2d690 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20 69 73 20  * ^The limit is 
2d6a0 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
2d6b0 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74  ecause if [sqlit
2d6c0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2d6d0 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66  y()].** cannot f
2d6e0 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
2d6f0 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
2d700 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
2d710 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
2d720 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
2d730 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
2d740 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
2d750 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
2d760 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 6e  eeds..**.** ^A n
2d770 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
2d780 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e  value for N mean
2d790 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
2d7a0 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  no soft heap lim
2d7b0 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  it and.** [sqlit
2d7c0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2d7d0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
2d7e0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65  e called when me
2d7f0 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65  mory is exhauste
2d800 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
2d810 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2d820 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d830 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
2d840 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  ^(SQLite makes a
2d850 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20   best effort to 
2d860 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68  honor the soft h
2d870 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75  eap limit..** Bu
2d880 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65  t if the soft he
2d890 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20  ap limit cannot 
2d8a0 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63  be honored, exec
2d8b0 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f  ution will.** co
2d8c0 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65  ntinue without e
2d8d0 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61  rror or notifica
2d8e0 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69 73  tion.)^  This is
2d8f0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
2d900 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73  s.** called a "s
2d910 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
2d920 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
2d930 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
2d940 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d950 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
2d960 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
2d970 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
2d980 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
2d990 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
2d9a0 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
2d9b0 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
2d9c0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
2d9d0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
2d9e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d9f0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
2da00 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
2da10 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
2da20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
2da30 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
2da40 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2da50 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
2da60 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
2da70 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
2da80 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
2da90 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
2daa0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
2dab0 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
2dac0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
2dad0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
2dae0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
2daf0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f  l threads..*/.vo
2db00 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2db10 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2db20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2db30 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2db40 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2db50 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
2db60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2db70 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
2db80 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
2db90 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
2dba0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
2dbb0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
2dbc0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
2dbd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dbe0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
2dbf0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
2dc00 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
2dc10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2dc20 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2dc30 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2dc40 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2dc50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2dc60 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2dc70 74 69 6f 6e 2e 20 5e 28 54 68 65 20 73 65 63 6f  tion. ^(The seco
2dc80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2dc90 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
2dca0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2dcb0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
2dcc0 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74   "temp" or an at
2dcd0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
2dce0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2dcf0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
2dd00 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69  le or NULL. If i
2dd10 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2dd20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
2dd30 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
2dd40 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
2dd50 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
2dd60 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73  ame algorithm us
2dd70 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
2dd80 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20  se engine to.** 
2dd90 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
2dda0 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
2ddb0 6e 63 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  nces.)^.**.** ^T
2ddc0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2ddd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2dde0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2ddf0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2de00 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
2de10 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
2de20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
2de30 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
2de40 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
2de50 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
2de60 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
2de70 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
2de80 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
2de90 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
2dea0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
2deb0 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
2dec0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
2ded0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2dee0 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
2def0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
2df00 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
2df10 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
2df20 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
2df30 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
2df40 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
2df50 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
2df60 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2df70 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2df80 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
2df90 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
2dfa0 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
2dfb0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2dfc0 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
2dfd0 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
2dfe0 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
2dff0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
2e000 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
2e010 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
2e020 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
2e030 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
2e040 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2e050 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2e060 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
2e070 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
2e080 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
2e090 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2e0a0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2e0b0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
2e0c0 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
2e0d0 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
2e0e0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2e0f0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2e100 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
2e110 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
2e120 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2e130 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
2e140 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
2e150 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
2e160 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2e170 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
2e180 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
2e190 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
2e1a0 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
2e1b0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
2e1c0 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
2e1d0 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
2e1e0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
2e1f0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
2e200 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
2e210 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
2e220 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2e230 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
2e240 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
2e250 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
2e260 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
2e270 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
2e280 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2e290 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
2e2a0 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
2e2b0 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
2e2c0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2e2d0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
2e2e0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
2e2f0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
2e300 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
2e310 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2e320 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2e330 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2e340 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2e350 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2e360 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2e370 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2e380 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2e390 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2e3a0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2e3b0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2e3c0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2e3d0 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2e3e0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2e3f0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2e400 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2e410 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
2e420 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
2e430 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
2e440 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
2e450 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
2e460 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
2e470 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
2e480 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
2e490 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
2e4a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
2e4b0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
2e4c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2e4d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2e4e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2e4f0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
2e500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e510 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
2e520 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
2e530 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
2e540 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
2e550 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
2e560 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2e570 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2e580 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2e590 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2e5a0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2e5b0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2e5c0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
2e5d0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
2e5e0 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
2e5f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2e600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e610 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
2e620 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2e630 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
2e640 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2e650 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
2e660 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e670 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
2e680 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
2e690 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
2e6a0 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
2e6b0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
2e6c0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2e6d0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
2e6e0 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
2e6f0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
2e700 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2e710 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
2e720 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
2e730 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
2e740 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
2e750 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
2e760 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2e770 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
2e780 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
2e790 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
2e7a0 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
2e7b0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2e7c0 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
2e7d0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
2e7e0 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
2e7f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2e800 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2e810 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
2e820 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
2e830 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
2e840 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
2e850 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2e860 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
2e870 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2e880 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
2e890 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
2e8a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
2e8b0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
2e8c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2e8d0 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
2e8e0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2e8f0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
2e900 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
2e910 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
2e920 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
2e930 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
2e940 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
2e950 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
2e960 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
2e970 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
2e980 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
2e990 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
2e9a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
2e9b0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
2e9c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2e9d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2e9e0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2e9f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2ea00 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2ea10 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
2ea20 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
2ea30 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
2ea40 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
2ea50 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2ea60 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
2ea70 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
2ea80 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
2ea90 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
2eaa0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
2eab0 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
2eac0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2ead0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2eae0 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
2eaf0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
2eb00 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
2eb10 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
2eb20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2eb30 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
2eb40 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
2eb50 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
2eb60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
2eb70 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2eb80 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
2eb90 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
2eba0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2ebb0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2ebc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
2ebd0 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
2ebe0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
2ebf0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
2ec00 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
2ec10 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
2ec20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2ec30 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
2ec40 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
2ec50 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
2ec60 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
2ec70 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
2ec80 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2ec90 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
2eca0 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
2ecb0 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
2ecc0 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
2ecd0 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
2ece0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
2ecf0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
2ed00 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
2ed10 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
2ed20 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
2ed30 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
2ed40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2ed50 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2ed60 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2ed70 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
2ed80 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
2ed90 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
2eda0 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
2edb0 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
2edc0 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
2edd0 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
2ede0 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
2edf0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
2ee00 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
2ee10 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
2ee20 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
2ee30 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
2ee40 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
2ee50 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
2ee60 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
2ee70 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2ee80 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
2ee90 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
2eea0 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2eeb0 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
2eec0 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
2eed0 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
2eee0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
2eef0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2ef00 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
2ef10 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
2ef20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2ef30 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2ef40 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2ef50 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
2ef60 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
2ef70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ef80 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2ef90 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
2efa0 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
2efb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2efc0 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
2efd0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2efe0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  s.**.** ^This AP
2eff0 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
2f000 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
2f010 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
2f020 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
2f030 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
2f040 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
2f050 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
2f060 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
2f070 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62  o all new [datab
2f080 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
2f090 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2f0a0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
2f0b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
2f0c0 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70  xtension entry p
2f0d0 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  oint.** in an ar
2f0e0 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61  ray that is obta
2f0f0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2f100 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
2f110 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  hat memory.** is
2f120 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
2f130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2f140 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2f150 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  .)^.**.** ^This 
2f160 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
2f170 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
2f180 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
2f190 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2f1a0 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65  ally invoked whe
2f1b0 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74  never a new [dat
2f1c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f1d0 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75  ].** is opened u
2f1e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
2f1f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2f200 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
2f210 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2f220 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63  2()]..** ^Duplic
2f230 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
2f240 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
2f250 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
2f260 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ine.** multiple 
2f270 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2f280 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
2f290 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41   harmless..** ^A
2f2a0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
2f2b0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
2f2c0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2f2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
2f2e0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
2f2f0 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28   (*xEntryPoint)(
2f300 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void));../*.** C
2f310 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2f320 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
2f330 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
2f340 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
2f350 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
2f360 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2f370 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  red automatic.**
2f380 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20   extensions. It 
2f390 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
2f3a0 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a  t of all prior.*
2f3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  * [sqlite3_auto_
2f3c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c  extension()] cal
2f3d0 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ls.)^.**.** ^Thi
2f3e0 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
2f3f0 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78  les automatic ex
2f400 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
2f410 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
2f420 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
2f430 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
2f440 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20  id);../*.****** 
2f450 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
2f460 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2f470 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
2f480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
2f490 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
2f4a0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
2f4b0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
2f4c0 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  m is currently c
2f4d0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
2f4e0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
2f4f0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
2f500 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
2f510 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
2f520 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
2f530 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
2f540 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
2f550 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
2f560 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
2f570 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
2f580 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
2f590 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
2f5a0 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
2f5b0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
2f5c0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
2f5d0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
2f5e0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
2f5f0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
2f600 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65  * Structures use
2f610 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
2f620 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
2f630 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2f640 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
2f650 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79  sqlite3_vtab;.ty
2f660 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2f670 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
2f680 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2f690 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  fo;.typedef stru
2f6a0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
2f6b0 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76  cursor sqlite3_v
2f6c0 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65  tab_cursor;.type
2f6d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2f6e0 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65  e3_module sqlite
2f6f0 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a  3_module;../*.**
2f700 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
2f710 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a  al Table Object.
2f720 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2f730 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72  ite3_module {vir
2f740 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2f750 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  e}.** EXPERIMENT
2f760 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74  AL.**.** This st
2f770 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d  ructure, sometim
2f780 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76  es called a a "v
2f790 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2f7a0 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65  ule", .** define
2f7b0 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  s the implementa
2f7c0 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75  tion of a [virtu
2f7d0 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a  al tables].  .**
2f7e0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
2f7f0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20  consists mostly 
2f800 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
2f810 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
2f820 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c   ^A virtual tabl
2f830 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61  e module is crea
2f840 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69  ted by filling i
2f850 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  n a persistent.*
2f860 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
2f870 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  is structure and
2f880 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74   passing a point
2f890 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61  er to that insta
2f8a0 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nce.** to [sqlit
2f8b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2f8c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f8d0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
2f8e0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67  ()]..** ^The reg
2f8f0 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
2f900 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
2f910 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
2f920 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
2f930 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
2f940 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f950 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
2f960 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
2f970 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
2f980 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
2f990 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
2f9a0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
2f9b0 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
2f9c0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
2f9d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
2f9e0 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
2f9f0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
2fa00 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
2fa10 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
2fa20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2fa30 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
2fa40 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
2fa50 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
2fa60 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
2fa70 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
2fa80 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
2fa90 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
2faa0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
2fab0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
2fac0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
2fad0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
2fae0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2faf0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
2fb00 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
2fb10 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
2fb20 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2fb30 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2fb40 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
2fb50 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
2fb60 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2fb70 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
2fb80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fb90 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fba0 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
2fbb0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
2fbc0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
2fbd0 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
2fbe0 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
2fbf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2fc00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
2fc10 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
2fc20 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
2fc30 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
2fc40 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
2fc50 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
2fc60 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
2fc70 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
2fc80 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
2fc90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
2fca0 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
2fcb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fcc0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
2fcd0 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
2fce0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
2fcf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2fd00 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
2fd10 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
2fd20 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
2fd30 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
2fd40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
2fd50 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
2fd60 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
2fd70 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
2fd80 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
2fd90 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
2fda0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2fdb0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
2fdc0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2fdd0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2fde0 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
2fdf0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2fe00 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
2fe10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2fe20 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2fe30 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
2fe40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2fe50 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
2fe60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2fe70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2fe80 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
2fe90 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
2fea0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2feb0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2fec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fed0 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
2fee0 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
2fef0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
2ff00 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
2ff10 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
2ff20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ff30 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2ff40 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
2ff50 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  tion.** KEYWORDS
2ff60 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  : sqlite3_index_
2ff70 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45  info.** EXPERIME
2ff80 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
2ff90 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
2ffa0 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
2ffb0 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
2ffc0 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  s is used to.** 
2ffd0 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
2ffe0 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
2fff0 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
30000 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   the [xBestIndex
30010 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  ].** method of a
30020 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
30030 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69  module].  The fi
30040 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
30050 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
30060 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
30070 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
30080 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
30090 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
300a0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
300b0 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
300c0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e   fields..**.** ^
300d0 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  (The aConstraint
300e0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
300f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30100 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
30110 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72   form:.**.** <pr
30120 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
30130 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  </pre>.**.** whe
30140 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
30150 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
30160 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 54 68 65  r &gt;=.)^  ^The
30170 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
30180 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
30190 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
301a0 5b 5d 2e 6f 70 2e 20 20 5e 54 68 65 20 69 6e 64  [].op.  ^The ind
301b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
301c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
301d0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
301e0 43 6f 6c 75 6d 6e 2e 20 20 5e 28 61 43 6f 6e 73  Column.  ^(aCons
301f0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
30200 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
30210 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
30220 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
30230 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
30240 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
30250 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
30260 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
30270 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
30280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
30290 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
302a0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
302b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
302c0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
302d0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
302e0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
302f0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
30300 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
30310 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
30320 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
30330 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
30340 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
30350 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
30360 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
30370 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
30380 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
30390 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
303a0 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
303b0 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
303c0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
303d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
303e0 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
303f0 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  * ^Information a
30400 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
30410 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
30420 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
30430 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20  ..** ^Each term 
30440 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
30450 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
30460 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
30470 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  use..**.** The [
30480 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68  xBestIndex] meth
30490 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
304a0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
304b0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
304c0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
304d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
304e0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e  s to xFilter.  ^
304f0 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
30500 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
30510 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
30520 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
30530 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
30540 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
30550 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
30560 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
30570 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20   in argv.  ^(If 
30580 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
30590 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
305a0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
305b0 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
305c0 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
305d0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
305e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
305f0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
30600 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
30610 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e.)^.**.** ^The 
30620 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
30630 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
30640 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
30650 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46   into the.** [xF
30660 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a  ilter] method..*
30670 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  * ^[sqlite3_free
30680 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
30690 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
306a0 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65  d only iff.** ne
306b0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
306c0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
306d0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
306e0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
306f0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
30700 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
30710 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
30720 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
30730 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
30740 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
30750 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
30760 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
30770 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
30780 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
30790 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
307a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
307b0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
307c0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
307d0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
307e0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
307f0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
30800 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
30810 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
30820 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
30830 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
30840 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
30850 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
30860 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
30870 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
30880 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
30890 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
308a0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
308b0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
308c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
308d0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
308e0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
308f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
30900 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
30910 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
30920 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
30930 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
30940 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
30950 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
30960 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
30970 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
30980 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
30990 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
309a0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
309b0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
309c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
309d0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
309e0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
309f0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
30a00 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
30a10 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
30a20 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
30a30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
30a40 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
30a50 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
30a60 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
30a70 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
30a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
30a90 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
30aa0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30ab0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
30ac0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
30ad0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
30ae0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
30af0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
30b00 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
30b10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
30b20 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
30b30 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
30b40 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
30b50 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
30b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30b70 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
30b80 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
30b90 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
30ba0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
30bb0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
30bc0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
30bd0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
30be0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
30bf0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
30c00 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
30c10 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
30c20 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
30c30 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
30c40 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
30c50 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
30c60 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
30c70 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
30c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30c90 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
30ca0 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
30cb0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
30cc0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
30cd0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
30ce0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
30cf0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
30d00 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
30d10 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
30d20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
30d30 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
30d40 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
30d50 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
30d60 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
30d70 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
30d80 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
30d90 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
30da0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
30db0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
30dc0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
30dd0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
30de0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
30df0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30e00 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
30e10 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30e20 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
30e30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
30e40 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30e50 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
30e60 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30e70 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
30e80 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
30e90 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
30ea0 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
30eb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
30ec0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
30ed0 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
30ee0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
30ef0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
30f00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
30f10 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
30f20 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30f30 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
30f40 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
30f50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30f60 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
30f70 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
30f80 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
30f90 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
30fa0 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
30fb0 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
30fc0 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65  he module, or be
30fd0 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
30fe0 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
30ff0 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
31000 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
31010 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
31020 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
31030 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
31040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
31050 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
31060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31070 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
31080 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
31090 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
310a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
310b0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
310c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
310d0 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
310e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
310f0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
31100 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
31110 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
31120 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
31130 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
31140 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
31150 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
31160 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
31170 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
31180 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
31190 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
311a0 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
311b0 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
311c0 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
311d0 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
311e0 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
311f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31200 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
31210 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
31220 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
31230 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
31240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
31250 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
31260 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
31270 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
31280 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
31290 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
312a0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
312b0 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
312c0 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
312d0 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
312e0 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
312f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31300 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
31310 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
31320 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
31330 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
31340 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
31350 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
31360 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
31370 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
31380 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
31390 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
313a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
313b0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
313c0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
313d0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
313e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
313f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
31400 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
31410 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
31420 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
31430 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
31440 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
31450 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20  id *pClientData 
31460 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
31470 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
31480 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
31490 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
314a0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
314b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
314c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
314d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
314e0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
314f0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
31500 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
31510 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
31520 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
31530 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
31540 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
31550 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
31560 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
31570 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
31580 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
31590 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f  tData,         /
315a0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
315b0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
315c0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
315d0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
315e0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
315f0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
31600 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
31610 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
31620 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
31630 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
31640 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
31650 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31660 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
31670 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
31680 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
31690 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
316a0 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a  s.** of this obj
316b0 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20  ect to describe 
316c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
316d0 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20  tance.** of the 
316e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
316f0 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
31700 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f  will.** be tailo
31710 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
31720 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
31730 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
31740 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70  tation..** The p
31750 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
31760 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
31770 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
31780 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a  ields that are.*
31790 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  * common to all 
317a0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
317b0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56  ations..**.** ^V
317c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
317d0 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
317e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
317f0 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
31800 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
31810 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
31820 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72  printf()] to zEr
31830 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
31840 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
31850 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
31860 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
31870 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
31880 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
31890 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61  )].** prior to a
318a0 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73  ssigning a new s
318b0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67  tring to zErrMsg
318c0 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72  .  ^After the er
318d0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
318e0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
318f0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
31900 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
31910 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
31920 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
31930 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
31940 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
31950 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
31960 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73   be zeroed..*/.s
31970 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
31980 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
31990 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
319a0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
319b0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
319c0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
319d0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
319e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
319f0 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53   /* NO LONGER US
31a00 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ED */.  char *zE
31a10 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
31a20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
31a30 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
31a40 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
31a50 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
31a60 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
31a70 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
31a80 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
31a90 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
31aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31ab0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
31ac0 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a  Cursor Object.**
31ad0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
31ae0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
31af0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
31b00 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d  rsor}.** EXPERIM
31b10 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72  ENTAL.**.** Ever
31b20 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
31b30 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
31b40 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
31b50 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
31b60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  * following stru
31b70 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
31b80 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
31b90 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  oint into the.**
31ba0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
31bb0 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
31bc0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
31bd0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
31be0 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
31bf0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
31c00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
31c10 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f  odule.xOpen | xO
31c20 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  pen] method of t
31c30 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72  he module and ar
31c40 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62  e destroyed.** b
31c50 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  y the [sqlite3_m
31c60 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78  odule.xClose | x
31c70 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20  Close] method.  
31c80 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64  Cursors are used
31c90 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c  .** by the [xFil
31ca0 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b  ter], [xNext], [
31cb0 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d  xEof], [xColumn]
31cc0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d  , and [xRowid] m
31cd0 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65  ethods.** of the
31ce0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
31cf0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
31d00 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
31d10 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
31d20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
31d30 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
31d40 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
31d50 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
31d60 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
31d70 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
31d80 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
31d90 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
31da0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
31db0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
31dc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
31dd0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
31de0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
31df0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
31e00 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
31e10 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
31e20 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
31e30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
31e40 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
31e50 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
31e60 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
31e70 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
31e80 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
31e90 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
31ea0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
31eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72  .**.** ^The [xCr
31ec0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
31ed0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
31ee0 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  a.** [virtual ta
31ef0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c  ble module] call
31f00 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a   this interface.
31f10 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
31f20 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
31f30 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
31f40 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
31f50 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
31f60 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
31f70 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51  implement..*/.SQ
31f80 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
31f90 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  L int sqlite3_de
31fa0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
31fb0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
31fc0 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *zSQL);../*.** C
31fd0 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
31fe0 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
31ff0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
32000 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
32010 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c  .**.** ^(Virtual
32020 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
32030 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
32040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32050 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
32060 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64  using the [xFind
32070 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64  Function] method
32080 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32090 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
320a0 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20   .** But global 
320b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
320c0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
320d0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
320e0 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
320f0 64 65 64 2e 29 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ded.).**.** ^(Th
32100 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
32110 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
32120 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
32130 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
32140 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
32150 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
32160 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
32170 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
32180 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
32190 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
321a0 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
321b0 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
321c0 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  )^  ^The impleme
321d0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
321e0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
321f0 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
32200 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
32210 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
32220 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
32230 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
32240 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
32250 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
32260 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
32270 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20  e a placeholder 
32280 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
32290 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a  n be overloaded.
322a0 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c  ** by a [virtual
322b0 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49   table]..*/.SQLI
322c0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
322d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
322e0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
322f0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
32300 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
32310 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
32320 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
32330 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
32340 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
32350 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
32360 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
32370 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
32380 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
32390 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
323a0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
323b0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
323c0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
323d0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
323e0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
323f0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
32400 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
32410 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
32420 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
32430 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
32440 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
32450 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
32460 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
32470 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
32480 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
32490 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
324a0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
324b0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
324c0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  s comment..**.**
324d0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
324e0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
324f0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
32500 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
32510 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ***.*/../*.** CA
32520 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
32530 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
32540 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42  .** KEYWORDS: {B
32550 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f  LOB handle} {BLO
32560 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a  B handles}.**.**
32570 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
32580 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
32590 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42  esents an open B
325a0 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  LOB on which.** 
325b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
325c0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
325d0 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62   BLOB I/O] can b
325e0 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20  e performed..** 
325f0 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73  ^Objects of this
32600 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65   type are create
32610 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
32620 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  ob_open()].** an
32630 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
32640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
32650 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b  se()]..** ^The [
32660 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
32670 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
32680 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
32690 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
326a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
326b0 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
326c0 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
326d0 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68  the BLOB..** ^Th
326e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
326f0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
32700 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
32710 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
32720 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
32730 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
32740 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
32750 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
32760 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
32770 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
32780 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28  tal I/O.**.** ^(
32790 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20  This interfaces 
327a0 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61  opens a [BLOB ha
327b0 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74  ndle | handle] t
327c0 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74  o the BLOB locat
327d0 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f  ed.** in row iRo
327e0 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d  w, column zColum
327f0 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20  n, table zTable 
32800 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b  in database zDb;
32810 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  .** in other wor
32820 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f  ds, the same BLO
32830 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20  B that would be 
32840 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
32850 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
32860 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
32870 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
32880 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69  HERE [rowid] = i
32890 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  Row;.** </pre>)^
328a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
328b0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
328c0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
328d0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
328e0 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20  ned for read.** 
328f0 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
32900 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f  . ^If it is zero
32910 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  , the BLOB is op
32920 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63  ened for read ac
32930 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  cess..** ^It is 
32940 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
32950 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
32960 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e  at is part of an
32970 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72   index or primar
32980 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72  y .** key for wr
32990 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65  iting. ^If [fore
329a0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
329b0 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  nts] are enabled
329c0 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20  , it is .** not 
329d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
329e0 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
329f0 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69  s part of a [chi
32a00 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74  ld key] for writ
32a10 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ing..**.** ^Note
32a20 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
32a30 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74  se name is not t
32a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74  he filename that
32a50 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
32a60 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61   database but ra
32a70 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69  ther the symboli
32a80 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  c name of the da
32a90 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61  tabase that.** a
32aa0 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65  ppears after the
32ab0 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e   AS keyword when
32ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
32ad0 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67   connected using
32ae0 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46   [ATTACH]..** ^F
32af0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
32b00 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
32b10 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
32b20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20  "main"..** ^For 
32b30 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
32b40 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
32b50 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
32b60 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  ^(On success, [S
32b70 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
32b80 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
32b90 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  w [BLOB handle] 
32ba0 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  is written.** to
32bb0 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77   *ppBlob. Otherw
32bc0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
32bd0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
32be0 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73  and *ppBlob is s
32bf0 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75  et.** to be a nu
32c00 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a  ll pointer.)^.**
32c10 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
32c20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
32c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
32c40 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
32c50 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
32c60 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
32c70 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
32c80 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
32c90 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
32ca0 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f  * functions. ^No
32cb0 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
32cc0 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
32cd0 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
32ce0 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
32cf0 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
32d00 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
32d10 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
32d20 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
32d30 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
32d40 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
32d50 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
32d60 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  utine..**.** ^(I
32d70 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61  f the row that a
32d80 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69   BLOB handle poi
32d90 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69  nts to is modifi
32da0 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44  ed by an.** [UPD
32db0 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20  ATE], [DELETE], 
32dc0 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49  or by [ON CONFLI
32dd0 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73  CT] side-effects
32de0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  .** then the BLO
32df0 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b  B handle is mark
32e00 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e  ed as "expired".
32e10 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65  .** This is true
32e20 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f   if any column o
32e30 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61  f the row is cha
32e40 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c  nged, even a col
32e50 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  umn.** other tha
32e60 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c  n the one the BL
32e70 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65  OB handle is ope
32e80 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c  n on.)^.** ^Call
32e90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  s to [sqlite3_bl
32ea0 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
32eb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
32ec0 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65  te()] for.** a e
32ed0 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64  xpired BLOB hand
32ee0 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  le fail with an 
32ef0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
32f00 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
32f10 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74  * ^(Changes writ
32f20 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ten into a BLOB 
32f30 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f  prior to the BLO
32f40 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e  B expiring are n
32f50 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62  ot.** rollback b
32f60 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
32f70 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
32f80 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
32f90 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
32fa0 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
32fb0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
32fc0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
32fd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74  .)^.**.** ^Use t
32fe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
32ff0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
33000 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
33010 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
33020 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
33030 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61    ^The size of a
33040 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
33050 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
33060 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
33070 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
33080 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
33090 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
330a0 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
330b0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
330c0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
330d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
330e0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
330f0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
33100 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
33110 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
33120 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
33130 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
33140 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
33150 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
33160 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
33170 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
33180 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
33190 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
331a0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
331b0 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
331c0 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
331d0 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
331e0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
331f0 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
33200 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
33210 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  ob_close()]..*/.
33220 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
33230 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
33240 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
33250 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
33260 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
33270 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
33280 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
33290 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
332a0 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
332b0 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
332c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
332d0 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
332e0 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  andle.**.** ^Clo
332f0 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
33300 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
33310 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42   ^Closing a BLOB
33320 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
33330 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
33340 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
33350 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
33360 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
33370 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
33380 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
33390 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
333a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
333b0 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
333c0 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e  mode]..** ^If an
333d0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
333e0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
333f0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
33400 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
33410 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
33420 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
33430 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
33440 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42   ^(Closing the B
33450 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
33460 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
33470 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
33480 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
33490 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
334a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
334b0 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
334c0 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
334d0 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
334e0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
334f0 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
33500 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
33510 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
33520 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a  eturn value.)^.*
33530 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20  *.** ^(The BLOB 
33540 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64  is closed uncond
33550 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e  itionally.  Even
33560 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   if this routine
33570 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65   returns.** an e
33580 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42  rror code, the B
33590 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f  LOB is still clo
335a0 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  sed.)^.**.** ^Ca
335b0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
335c0 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
335d0 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20  ointer (such as 
335e0 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
335f0 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64  d.** by a failed
33600 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33610 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
33620 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33630 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
33640 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
33650 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
33660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33670 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
33680 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
33690 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20  .**.** ^Returns 
336a0 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
336b0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
336c0 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
336d0 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
336e0 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
336f0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
33700 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  ly argument.  ^T
33710 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  he.** incrementa
33720 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69  l blob I/O routi
33730 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61  nes can only rea
33740 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67  d or overwriting
33750 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f   existing.** blo
33760 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20  b content; they 
33770 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
33780 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
33790 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
337a0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
337b0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
337c0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
337d0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
337e0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
337f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
33800 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
33810 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
33820 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
33830 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
33840 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
33850 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
33860 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
33870 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
33880 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
33890 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
338a0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
338b0 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  vior..*/.int sql
338c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
338d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
338e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
338f0 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d  : Read Data From
33900 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
33910 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tally.**.** ^(Th
33920 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
33930 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
33940 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42   from an open [B
33950 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  LOB handle] into
33960 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
33970 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
33980 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
33990 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
339a0 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74  ffer Z.** from t
339b0 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
339c0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
339d0 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a   iOffset.)^.**.*
339e0 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
339f0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
33a00 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
33a10 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
33a20 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
33a30 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
33a40 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
33a50 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72   read.  ^If N or
33a60 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
33a70 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
33a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
33a90 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
33aa0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
33ab0 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74  * ^The size of t
33ac0 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e  he blob (and hen
33ad0 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
33ae0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
33af0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
33b00 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
33b10 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
33b20 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
33b30 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
33b40 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72  tempt to read fr
33b50 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  om an expired [B
33b60 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
33b70 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
33b80 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
33b90 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
33ba0 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73   ^(On success, s
33bb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
33bc0 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
33bd0 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
33be0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
33bf0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
33c00 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
33c10 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
33c20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33c30 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
33c40 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
33c50 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
33c60 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
33c70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
33c80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33c90 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
33ca0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
33cb0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
33cc0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
33cd0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
33ce0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
33cf0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
33d00 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
33d10 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
33d20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
33d30 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
33d40 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
33d50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
33d60 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _write()]..*/.in
33d70 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
33d80 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
33d90 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
33da0 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
33db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33dc0 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
33dd0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
33de0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  entally.**.** ^T
33df0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
33e00 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
33e10 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
33e20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
33e30 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
33e40 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
33e50 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61  ^N bytes of data
33e60 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
33e70 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
33e80 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
33e90 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
33ea0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
33eb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
33ec0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73  BLOB handle] pas
33ed0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
33ee0 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f   argument was no
33ef0 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20  t opened for.** 
33f00 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61  writing (the fla
33f10 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
33f20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
33f30 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c  en()] was zero),
33f40 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
33f50 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
33f60 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
33f70 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
33f80 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66  n may only modif
33f90 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  y the contents o
33fa0 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69  f the BLOB; it i
33fb0 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
33fc0 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  e to increase th
33fd0 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  e size of a BLOB
33fe0 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e   using this API.
33ff0 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
34000 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
34010 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
34020 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
34030 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
34040 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
34050 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
34060 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66  is written.  ^If
34070 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
34080 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
34090 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
340a0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
340b0 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
340c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
340d0 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
340e0 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
340f0 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
34100 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34110 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
34120 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34130 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
34140 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
34150 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20   to write to an 
34160 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
34170 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
34180 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
34190 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
341a0 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f  RT].  ^Writes to
341b0 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f   the BLOB that o
341c0 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72  ccurred.** befor
341d0 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  e the [BLOB hand
341e0 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20  le] expired are 
341f0 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  not rolled back 
34200 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61  by the.** expira
34210 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64  tion of the hand
34220 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  le, though of co
34230 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67  urse those chang
34240 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65  es might.** have
34250 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65   been overwritte
34260 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  n by the stateme
34270 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20  nt that expired 
34280 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a  the BLOB handle.
34290 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69  ** or by other i
342a0 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65  ndependent state
342b0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  ments..**.** ^(O
342c0 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74  n success, sqlit
342d0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20  e3_blob_write() 
342e0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
342f0 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
34300 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
34310 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
34320 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
34330 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34340 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34350 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34360 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34370 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
34380 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
34390 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
343a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
343b0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
343c0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
343d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
343e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
343f0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
34400 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34410 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34420 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
34430 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
34440 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
34450 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
34460 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
34470 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
34480 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ead()]..*/.int s
34490 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
344a0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
344b0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
344c0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
344d0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
344e0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
344f0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
34500 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  ts.**.** A virtu
34510 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
34520 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
34530 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
34540 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
34550 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
34560 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
34570 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
34580 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
34590 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
345a0 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
345b0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
345c0 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
345d0 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
345e0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
345f0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
34600 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
34610 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
34620 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
34630 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
34640 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
34650 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
34660 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73  ^The sqlite3_vfs
34670 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
34680 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
34690 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
346a0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
346b0 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20  ^Names are case 
346c0 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e  sensitive..** ^N
346d0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
346e0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
346f0 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74  trings..** ^If t
34700 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
34710 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  , a NULL pointer
34720 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
34730 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73   ^If zVfsName is
34740 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
34750 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
34760 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  turned..**.** ^N
34770 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
34780 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
34790 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
347a0 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65  r()..** ^Each ne
347b0 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
347c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
347d0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
347e0 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54  ag is set..** ^T
347f0 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
34800 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
34810 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
34820 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
34830 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73  ^To make an exis
34840 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
34850 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
34860 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
34870 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
34880 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
34890 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
348a0 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
348b0 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
348c0 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
348d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
348e0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
348f0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
34900 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
34910 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
34920 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
34930 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
34940 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
34950 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67  ed..**.** ^Unreg
34960 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
34970 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
34980 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
34990 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66  terface..** ^(If
349a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
349b0 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64   is unregistered
349c0 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73  , another VFS is
349d0 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68   chosen as.** th
349e0 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20  e default.  The 
349f0 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e  choice for the n
34a00 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72  ew VFS is arbitr
34a10 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65  ary.)^.*/.sqlite
34a20 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
34a30 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
34a40 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
34a50 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
34a60 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
34a70 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
34a80 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
34a90 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
34aa0 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
34ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ac0 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Mutexes.**.** Th
34ad0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
34ae0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
34af0 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
34b00 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
34b10 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
34b20 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
34b30 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
34b40 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
34b50 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
34b60 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
34b70 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
34b80 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34b90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
34ba0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
34bb0 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
34bc0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
34bd0 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ions.** of these
34be0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
34bf0 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
34c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
34c10 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
34c20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
34c30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e  compile-time.  ^
34c40 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  (The following.*
34c50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34c60 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
34c70 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
34c80 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
34c90 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
34ca0 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
34cb0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
34cc0 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
34cd0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34ce0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
34cf0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
34d00 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
34d10 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
34d20 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e  EX_NOOP implemen
34d30 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20  tation is a set 
34d40 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74  of routines.** t
34d50 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
34d60 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
34d70 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
34d80 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67  use in.** a sing
34d90 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  le-threaded appl
34da0 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53  ication.  ^The S
34db0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
34dc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
34dd0 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
34de0 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
34df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
34e00 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
34e10 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
34e20 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
34e30 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  dows..**.** ^(If
34e40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
34e50 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
34e60 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
34e70 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
34e80 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
34e90 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
34ea0 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
34eb0 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
34ec0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34ed0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
34ee0 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49  h the library. I
34ef0 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a  n this case the.
34f00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  ** application m
34f10 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73  ust supply a cus
34f20 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  tom mutex implem
34f30 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74  entation using t
34f40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
34f50 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
34f60 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  on of the sqlite
34f70 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74  3_config() funct
34f80 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61  ion.** before ca
34f90 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e  lling sqlite3_in
34fa0 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e  itialize() or an
34fb0 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73  y other public s
34fc0 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74  qlite3_.** funct
34fd0 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73  ion that calls s
34fe0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
34ff0 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  e().)^.**.** ^Th
35000 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
35010 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
35020 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
35030 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
35040 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35050 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74  o it. ^If it ret
35060 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61  urns NULL.** tha
35070 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d  t means that a m
35080 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62  utex could not b
35090 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53  e allocated.  ^S
350a0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
350b0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
350c0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
350d0 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  or.  ^(The argum
350e0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
350f0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
35100 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
35110 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
35120 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
35130 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
35140 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
35150 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
35160 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
35170 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
35180 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
35190 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
351a0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
351b0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
351c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
351d0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
351e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
351f0 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
35200 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
35210 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  RU.** <li>  SQLI
35220 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
35230 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  LRU2.** </ul>)^.
35240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
35250 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28   two constants (
35260 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
35270 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  T and SQLITE_MUT
35280 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a  EX_RECURSIVE).**
35290 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
352a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
352b0 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
352c0 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77  mutex.  ^The new
352d0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
352e0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
352f0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
35300 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
35310 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
35320 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
35330 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
35340 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
35350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
35360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
35370 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
35380 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
35390 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
353a0 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
353b0 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
353c0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
353d0 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69   to.  ^SQLite wi
353e0 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
353f0 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
35400 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
35410 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
35420 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20  eds one.  ^If a 
35430 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
35440 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
35450 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
35460 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
35470 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
35480 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
35490 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
354a0 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
354b0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
354c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
354d0 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74  T..**.** ^The ot
354e0 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61  her allowed para
354f0 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65  meters to sqlite
35500 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
35510 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a  (anything other.
35520 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  ** than SQLITE_M
35530 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51  UTEX_FAST and SQ
35540 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
35550 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72  SIVE) each retur
35560 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
35570 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
35580 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e  isting mutex.  ^
35590 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78  Six static mutex
355a0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62  es are.** used b
355b0 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65  y the current ve
355c0 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e  rsion of SQLite.
355d0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
355e0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
355f0 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ay add additiona
35600 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
35610 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65  .  Static mutexe
35620 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e  s are for intern
35630 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
35640 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ite only.  Appli
35650 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
35660 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20   SQLite mutexes 
35670 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e  should.** use on
35680 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  ly the dynamic m
35690 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20  utexes returned 
356a0 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  by SQLITE_MUTEX_
356b0 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54  FAST or.** SQLIT
356c0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
356d0 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  E..**.** ^Note t
356e0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
356f0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
35700 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
35710 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
35720 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
35730 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
35740 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
35750 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
35760 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
35770 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
35780 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74  very call.  ^But
35790 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a   for the static.
357a0 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
357b0 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
357c0 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
357d0 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
357e0 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
357f0 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
35800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
35810 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
35820 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
35830 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
35840 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
35850 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65   mutex.  ^SQLite
35860 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
35870 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
35880 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
35890 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
358a0 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
358b0 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
358c0 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77  t be in.** use w
358d0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
358e0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
358f0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
35900 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
35910 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
35920 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
35930 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65  ior.  ^SQLite ne
35940 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
35950 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
35960 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  x..**.** ^The sq
35970 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
35980 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
35990 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
359a0 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
359b0 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
359c0 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74  .  ^If another t
359d0 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
359e0 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
359f0 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
35a00 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
35a10 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74   block and sqlit
35a20 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77  e3_mutex_try() w
35a30 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  ill return.** SQ
35a40 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65  LITE_BUSY.  ^The
35a50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35a60 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
35a70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
35a80 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
35a90 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28  ssful entry.  ^(
35aa0 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20  Mutexes created 
35ab0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
35ac0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
35ad0 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d  can be entered m
35ae0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79  ultiple times by
35af0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35b00 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73  ..** In such cas
35b10 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
35b20 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
35b30 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
35b40 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
35b50 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
35b60 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20  * can enter.)^  
35b70 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  ^(If the same th
35b80 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
35b90 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
35ba0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
35bb0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
35bc0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
35bd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c  ndefined..** SQL
35be0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
35bf0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
35c00 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
35c10 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
35c20 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d  s.)^.**.** ^(Som
35c30 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
35c40 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
35c50 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
35c60 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
35c70 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
35c80 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
35c90 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
35ca0 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
35cb0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
35cc0 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
35cd0 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
35ce0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
35cf0 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65  re only ever use
35d00 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  s.** sqlite3_mut
35d10 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f  ex_try() as an o
35d20 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74  ptimization so t
35d30 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c  his is acceptabl
35d40 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a  e behavior.)^.**
35d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35d60 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72  _mutex_leave() r
35d70 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d  outine exits a m
35d80 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a  utex that was.**
35d90 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65   previously ente
35da0 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20  red by the same 
35db0 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20  thread.   ^(The 
35dc0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
35dd0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
35de0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
35df0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
35e00 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
35e10 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
35e20 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
35e30 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77  cated.  SQLite w
35e40 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
35e50 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  either.)^.**.** 
35e60 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
35e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
35e80 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
35e90 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
35ea0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
35eb0 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
35ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
35ed0 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
35ee0 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
35ef0 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
35f00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35f10 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
35f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35f30 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
35f40 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
35f50 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
35f60 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
35f70 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
35f80 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
35f90 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
35fa0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
35fb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
35fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
35fd0 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
35fe0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
35ff0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
36000 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
36010 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36020 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
36030 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52   Object.** EXPER
36040 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
36050 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
36060 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  s structure defi
36070 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65  nes the low-leve
36080 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  l routines.** us
36090 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  ed to allocate a
360a0 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a  nd use mutexes..
360b0 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74  **.** Usually, t
360c0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
360d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
360e0 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c   provided by SQL
360f0 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69  ite are.** suffi
36100 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74  cient, however t
36110 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20  he user has the 
36120 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69  option of substi
36130 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a  tuting a custom.
36140 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
36150 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65  n for specialize
36160 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72  d deployments or
36170 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69   systems for whi
36180 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65  ch SQLite.** doe
36190 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  s not provide a 
361a0 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
361b0 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  ntation. In this
361c0 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a   case, the user.
361d0 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70  ** creates and p
361e0 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74  opulates an inst
361f0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
36200 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a  ucture to pass.*
36210 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  * to sqlite3_con
36220 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68  fig() along with
36230 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
36240 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
36250 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  n..** Additional
36260 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ly, an instance 
36270 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
36280 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  e can be used as
36290 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61   an.** output va
362a0 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72  riable when quer
362b0 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20  ying the system 
362c0 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
362d0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
362e0 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74  ntation, using t
362f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
36300 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69  G_GETMUTEX] opti
36310 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  on..**.** ^The x
36320 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
36330 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
36340 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
36350 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
36360 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69   of system initi
36370 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65  alization by the
36380 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
36390 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a  ize() function..
363a0 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e  ** ^The xMutexIn
363b0 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  it routine is ca
363c0 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78  lle by SQLite ex
363d0 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
363e0 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65  ach.** effective
363f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36400 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e  3_initialize()].
36410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
36420 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66  exEnd method def
36430 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
36440 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
36450 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
36460 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20  system shutdown 
36470 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
36480 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69  hutdown() functi
36490 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65  on. The.** imple
364a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
364b0 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65  s method is expe
364c0 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  cted to release 
364d0 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a  all outstanding.
364e0 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74  ** resources obt
364f0 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74  ained by the mut
36500 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65  ex methods imple
36510 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63  mentation, espec
36520 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f  ially.** those o
36530 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78  btained by the x
36540 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
36550 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e  .  ^The xMutexEn
36560 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
36570 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   is invoked exac
36580 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  tly once for eac
36590 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
365a0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
365b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61  **.** ^(The rema
365c0 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68  ining seven meth
365d0 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74  ods defined by t
365e0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78  his structure (x
365f0 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78  MutexAlloc,.** x
36600 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65  MutexFree, xMute
36610 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72  xEnter, xMutexTr
36620 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20  y, xMutexLeave, 
36630 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a  xMutexHeld and.*
36640 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  * xMutexNotheld)
36650 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66   implement the f
36660 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
36670 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c  ces (respectivel
36680 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y):.**.** <ul>.*
36690 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
366a0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
366b0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
366c0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
366d0 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a  x_free()] </li>.
366e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
366f0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
36700 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
36710 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36720 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a  ex_try()] </li>.
36730 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
36740 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36750 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
36760 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36770 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  ex_held()] </li>
36780 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36790 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
367a0 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  ld()] </li>.** <
367b0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
367c0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
367d0 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62   is that the pub
367e0 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20  lic sqlite3_XXX 
367f0 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72  functions enumer
36800 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69  ated.** above si
36810 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e  lently ignore an
36820 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68  y invocations th
36830 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70  at pass a NULL p
36840 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
36850 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  * of a valid mut
36860 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69  ex handle. The i
36870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
36880 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65  f the methods de
36890 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  fined.** by this
368a0 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e   structure are n
368b0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68  ot required to h
368c0 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c  andle this case,
368d0 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20   the results.** 
368e0 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c  of passing a NUL
368f0 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
36900 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  d of a valid mut
36910 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e  ex handle are un
36920 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e  defined.** (i.e.
36930 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c   it is acceptabl
36940 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20  e to provide an 
36950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
36960 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66  hat segfaults if
36970 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64  .** it is passed
36980 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29   a NULL pointer)
36990 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
369a0 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20  exInit() method 
369b0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
369c0 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65  fe.  ^It must be
369d0 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20   harmless to.** 
369e0 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69  invoke xMutexIni
369f0 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65  t() mutiple time
36a00 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
36a10 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69  e process and wi
36a20 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65  thout.** interve
36a30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d  ning calls to xM
36a40 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f  utexEnd().  Seco
36a50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
36a60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d  t calls to.** xM
36a70 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
36a80 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
36a90 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d   ^xMutexInit() m
36aa0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
36ab0 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
36ac0 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
36ad0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
36ae0 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
36af0 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d    ^Similarly, xM
36b00 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74  utexAlloc() must
36b10 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
36b20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
36b30 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69  tion for a stati
36b40 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76  c mutex.  ^Howev
36b50 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  er xMutexAlloc()
36b60 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a   may use SQLite.
36b70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
36b80 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20  tion for a fast 
36b90 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  or recursive mut
36ba0 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ex..**.** ^SQLit
36bb0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
36bc0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65  e xMutexEnd() me
36bd0 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  thod when [sqlit
36be0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69  e3_shutdown()] i
36bf0 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74  s.** called, but
36c00 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69   only if the pri
36c10 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65  or call to xMute
36c20 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53  xInit returned S
36c30 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20  QLITE_OK..** If 
36c40 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73  xMutexInit fails
36c50 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20   in any way, it 
36c60 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63  is expected to c
36c70 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74  lean up after it
36c80 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  self.** prior to
36c90 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74   returning..*/.t
36ca0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
36cb0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
36cc0 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ods sqlite3_mute
36cd0 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  x_methods;.struc
36ce0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
36cf0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
36d00 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f  (*xMutexInit)(vo
36d10 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  id);.  int (*xMu
36d20 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20  texEnd)(void);. 
36d30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a   sqlite3_mutex *
36d40 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69  (*xMutexAlloc)(i
36d50 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
36d60 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65  utexFree)(sqlite
36d70 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
36d80 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72  id (*xMutexEnter
36d90 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
36da0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
36db0 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d  exTry)(sqlite3_m
36dc0 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
36dd0 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73  (*xMutexLeave)(s
36de0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
36df0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48  .  int (*xMutexH
36e00 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
36e10 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
36e20 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71  MutexNotheld)(sq
36e30 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
36e40 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
36e50 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69  EF: Mutex Verifi
36e60 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
36e70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36e80 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
36e90 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
36ea0 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
36eb0 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
36ec0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
36ed0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
36ee0 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51  ements.  ^The SQ
36ef0 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
36f00 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
36f10 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
36f20 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
36f30 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
36f40 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
36f50 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
36f60 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
36f70 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f    ^The SQLite co
36f80 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
36f90 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
36fa0 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
36fb0 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
36fc0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
36fd0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
36fe0 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65  BUG flag.  ^Exte
36ff0 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65  rnal mutex imple
37000 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
37010 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20  e only required 
37020 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65  to provide these
37030 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c   routines if SQL
37040 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20  ITE_DEBUG is.** 
37050 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e  defined and if N
37060 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66  DEBUG is not def
37070 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
37080 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
37090 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
370a0 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
370b0 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
370c0 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
370d0 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
370e0 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
370f0 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
37100 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
37110 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75  tion is not requ
37120 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64  ired to provided
37130 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
37140 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
37150 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
37160 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  k. If the implem
37170 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
37180 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
37190 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
371a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
371b0 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
371c0 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
371d0 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a  s that always.**
371e0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
371f0 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
37200 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61  t get spurious a
37210 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65  ssertion failure
37220 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
37230 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37240 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
37250 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
37260 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
37270 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
37280 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20  eturn 1.   This 
37290 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
372a0 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
372b0 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
372c0 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
372d0 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
372e0 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
372f0 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
37300 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
37310 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
37320 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
37330 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
37340 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
37350 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
37360 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
37370 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f  g the.** call to
37380 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
37390 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73  eld() to fail, s
373a0 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  o a non-zero ret
373b0 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70  urn is.** the ap
373c0 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20  propriate thing 
373d0 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c  to do.  ^The sql
373e0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
373f0 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ld().** interfac
37400 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65  e should also re
37410 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65  turn 1 when give
37420 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
37430 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45  ..*/.#ifndef NDE
37440 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  BUG.int sqlite3_
37450 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
37460 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
37470 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37480 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
37490 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  tex*);.#endif../
374a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
374b0 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a  utex Types.**.**
374c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
374d0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
374e0 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
374f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
37500 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
37510 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
37520 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
37530 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74   The set of stat
37540 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63  ic mutexes may c
37550 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53  hange from one S
37560 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f  QLite release to
37570 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
37580 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
37590 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75   override the bu
375a0 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67  ilt-in mutex log
375b0 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72  ic must be.** pr
375c0 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d  epared to accomm
375d0 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c  odate additional
375e0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
375f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
37600 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20  TE_MUTEX_FAST   
37610 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
37620 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37630 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
37640 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
37650 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37660 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66  MASTER    2.#def
37670 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37680 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20  _STATIC_MEM     
37690 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    3  /* sqlite3_
376a0 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66  malloc() */.#def
376b0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
376c0 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20  _STATIC_MEM2    
376d0 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44    4  /* NOT USED
376e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
376f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37700 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20  OPEN      4  /* 
37710 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e  sqlite3BtreeOpen
37720 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
37730 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37740 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f  C_PRNG      5  /
37750 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  * sqlite3_random
37760 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
37770 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37780 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f  C_LRU       6  /
37790 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
377a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
377b0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
377c0 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c  RU2      7  /* l
377d0 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
377e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
377f0 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75   Retrieve the mu
37800 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61  tex for a databa
37810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
37820 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
37830 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37840 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74  inter the [sqlit
37850 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
37860 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c   that .** serial
37870 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74  izes access to t
37880 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37890 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69  nection] given i
378a0 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  n the argument.*
378b0 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65  * when the [thre
378c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53  ading mode] is S
378d0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49  erialized..** ^I
378e0 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  f the [threading
378f0 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65   mode] is Single
37900 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69  -thread or Multi
37910 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69  -thread then thi
37920 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  s.** routine ret
37930 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
37940 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
37950 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64  mutex *sqlite3_d
37960 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a  b_mutex(sqlite3*
37970 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37980 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f  EF: Low-Level Co
37990 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73  ntrol Of Databas
379a0 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  e Files.**.** ^T
379b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
379c0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
379d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
379e0 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
379f0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
37a00 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
37a10 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
37a20 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
37a30 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
37a40 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
37a50 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
37a60 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
37a70 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20  gument. ^The.** 
37a80 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
37a90 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20  base "main" for 
37aa0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
37ab0 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20  e or "temp" for 
37ac0 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61  the.** TEMP data
37ad0 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d  base, or the nam
37ae0 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61  e that appears a
37af0 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
37b00 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ord for.** datab
37b10 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64  ases that are ad
37b20 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41  ded using the [A
37b30 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61  TTACH] SQL comma
37b40 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70  nd..** ^A NULL p
37b50 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73  ointer can be us
37b60 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  ed in place of "
37b70 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74  main" to refer t
37b80 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61  o the.** main da
37b90 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20  tabase file..** 
37ba0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
37bb0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
37bc0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
37bd0 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64  .** are passed d
37be0 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20  irectly through 
37bf0 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  to the second an
37c00 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  d third paramete
37c10 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69  rs of.** the xFi
37c20 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
37c30 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  .  ^The return v
37c40 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c  alue of the xFil
37c50 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68  eControl.** meth
37c60 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72  od becomes the r
37c70 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
37c80 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
37c90 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
37ca0 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62  d parameter (zDb
37cb0 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d  Name) does not m
37cc0 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66  atch the name of
37cd0 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74   any.** open dat
37ce0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e  abase file, then
37cf0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73   SQLITE_ERROR is
37d00 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69   returned.  ^Thi
37d10 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
37d20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
37d30 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
37d40 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
37d50 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
37d60 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
37d70 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65  _errmsg()].  The
37d80 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c   underlying xFil
37d90 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
37da0 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65  might.** also re
37db0 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  turn SQLITE_ERRO
37dc0 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20  R.  There is no 
37dd0 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69  way to distingui
37de0 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e  sh between.** an
37df0 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61   incorrect zDbNa
37e00 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45  me and an SQLITE
37e10 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72  _ERROR return fr
37e20 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  om the underlyin
37e30 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  g.** xFileContro
37e40 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  l method..**.** 
37e50 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
37e60 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
37e70 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  E].*/.int sqlite
37e80 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73  3_file_control(s
37e90 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
37ea0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e  har *zDbName, in
37eb0 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t op, void*);../
37ec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
37ed0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
37ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37ef0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
37f00 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
37f10 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74  used to read out
37f20 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61   internal.** sta
37f30 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64  te of SQLite and
37f40 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74   to inject fault
37f50 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f  s into SQLite fo
37f60 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72  r testing.** pur
37f70 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72  poses.  ^The fir
37f80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
37f90 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  an operation cod
37fa0 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  e that determine
37fb0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c  s.** the number,
37fc0 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70   meaning, and op
37fd0 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73  eration of all s
37fe0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
37ff0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ters..**.** This
38000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
38010 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70  t for use by app
38020 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65  lications.  It e
38030 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20  xists solely.** 
38040 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68  for verifying th
38050 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74  e correct operat
38060 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
38070 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65  e library.  Depe
38080 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20  nding.** on how 
38090 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
380a0 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20  ry is compiled, 
380b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d  this interface m
380c0 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a  ight not exist..
380d0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
380e0 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  s of the operati
380f0 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20  on codes, their 
38100 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61  meanings, the pa
38110 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79  rameters.** they
38120 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20   take, and what 
38130 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20  they do are all 
38140 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
38150 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
38160 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74  ..** Unlike most
38170 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41   of the SQLite A
38180 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  PI, this functio
38190 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  n is not guarant
381a0 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74  eed to.** operat
381b0 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66  e consistently f
381c0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
381d0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
381e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74  int sqlite3_test
381f0 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c  _control(int op,
38200 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
38210 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20  PI3REF: Testing 
38220 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74  Interface Operat
38230 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
38240 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
38250 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70  are the valid op
38260 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72  eration code par
38270 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20  ameters used.** 
38280 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
38290 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
382a0 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29  3_test_control()
382b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70  ]..**.** These p
382c0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68  arameters and th
382d0 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65  eir meanings are
382e0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
382f0 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f  ge.** without no
38300 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c  tice.  These val
38310 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74  ues are for test
38320 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c  ing purposes onl
38330 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  y..** Applicatio
38340 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73  ns should not us
38350 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70  e any of these p
38360 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65  arameters or the
38370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73  .** [sqlite3_tes
38380 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  t_control()] int
38390 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
383a0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
383b0 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20  RL_PRNG_SAVE    
383c0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
383d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
383e0 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f  TCTRL_PRNG_RESTO
383f0 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36  RE             6
38400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38410 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45  TESTCTRL_PRNG_RE
38420 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20  SET             
38430 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
38440 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56  TE_TESTCTRL_BITV
38450 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20  EC_TEST         
38460 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
38470 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46  QLITE_TESTCTRL_F
38480 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20  AULT_INSTALL    
38490 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
384a0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
384b0 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f  L_BENIGN_MALLOC_
384c0 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65  HOOKS     10.#de
384d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
384e0 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54  CTRL_PENDING_BYT
384f0 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  E            11.
38500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
38510 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 20  ESTCTRL_ASSERT  
38520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38530 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
38540 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59  E_TESTCTRL_ALWAY
38550 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
38560 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
38570 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 45  LITE_TESTCTRL_RE
38580 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20 20  SERVE           
38590 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20        14../*.** 
385a0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65  CAPI3REF: SQLite
385b0 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 0a   Runtime Status.
385c0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
385d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
385e0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
385f0 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d   retrieve runtim
38600 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61  e status informa
38610 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68  tion.** about th
38620 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66  e preformance of
38630 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74   SQLite, and opt
38640 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74  ionally to reset
38650 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68   various.** high
38660 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e 54  water marks.  ^T
38670 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
38680 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
38690 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
386a0 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74  specific paramet
386b0 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20  er to measure.  
386c0 5e 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65  ^Recognized inte
386d0 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65  ger codes.** are
386e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51   of the form [SQ
386f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f  LITE_STATUS_MEMO
38700 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45  RY_USED | SQLITE
38710 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a  _STATUS_...]..**
38720 20 5e 54 68 65 20 63 75 72 72 65 6e 74 20 76 61   ^The current va
38730 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d  lue of the param
38740 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  eter is returned
38750 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e   into *pCurrent.
38760 0a 2a 2a 20 5e 54 68 65 20 68 69 67 68 65 73 74  .** ^The highest
38770 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20   recorded value 
38780 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  is returned in *
38790 70 48 69 67 68 77 61 74 65 72 2e 20 20 5e 49 66  pHighwater.  ^If
387a0 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61   the.** resetFla
387b0 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  g is true, then 
387c0 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f  the highest reco
387d0 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 65  rd value is rese
387e0 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67  t after.** *pHig
387f0 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74 65  hwater is writte
38800 6e 2e 20 20 5e 28 53 6f 6d 65 20 70 61 72 61 6d  n.  ^(Some param
38810 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63  eters do not rec
38820 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a  ord the highest.
38830 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74  ** value.  For t
38840 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a  hose parameters.
38850 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72  ** nothing is wr
38860 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67  itten into *pHig
38870 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72  hwater and the r
38880 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f  esetFlag is igno
38890 72 65 64 2e 29 5e 0a 2a 2a 20 5e 28 4f 74 68 65  red.)^.** ^(Othe
388a0 72 20 70 61 7