/ Hex Artifact Content
Login

Artifact 092df034f4b426ffbb9e5bb905958fa35bbb7f7a:


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 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
59b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
59c0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
59e0: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
59f0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5a00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5a10: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a20: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5a40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a50: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5a60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5a70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a80: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5aa0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5ab0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
5ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5ad0: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
5ae0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5b00: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
5b10: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
5b20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
5b30: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
5b40: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5b50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5b60: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
5b70: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5b80: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b90: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
5ba0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
5bb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5bc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5bd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5be0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5bf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5c00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5c10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5c20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5c30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5c40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5c50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5c60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5c90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5ca0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5cb0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5cc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5cd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5cf0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5d20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5d30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5d40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5d50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5d60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5d70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5d80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5d90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5da0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5db0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5dc0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5dd0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5de0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5df0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5e00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5e10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5e20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5e30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5e40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5e50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5e60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5e70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5e80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5e90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5ea0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5eb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5ec0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5ed0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5ee0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ef0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5f00: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
5f10: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
5f20: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
5f30: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
5f40: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
5f50: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
5f60: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
5f70: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
5f80: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
5f90: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
5fa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
5fb0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
5fc0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
5fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5fe0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
5ff0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6000: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6010: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6020: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
6030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6040: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6050: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6060: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
6070: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
6080: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
6090: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
60a0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
60b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
60c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
60d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
60e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
60f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6100: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6110: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6120: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6130: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6150: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
6160: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
6170: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
6180: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
6190: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
61a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
61b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
61c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
61d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
61e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
61f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6200: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6210: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6220: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6230: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6240: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6250: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
6260: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
6270: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
6280: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
6290: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
62a0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
62b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
62c0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
62d0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
62e0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
62f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6300: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6310: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6320: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6330: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6340: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6350: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
6360: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
6370: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
6380: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
6390: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
63a0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
63b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63c0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
63d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65   xOpen method se
63e0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
63f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6400: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
6410: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
6420: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
6430: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
6440: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
6450: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
6460: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65   if the xOpen re
6470: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
6480: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
6490: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
64a0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
64b0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
64c0: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20  failed xOpen.** 
64d0: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e  is for the xOpen
64e0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
64f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6500: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c  s element to NUL
6510: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
6520: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
6530: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
6540: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
6550: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
6560: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
6570: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
6580: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
6590: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
65a0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
65b0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
65c0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
65d0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
65e0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
65f0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
6600: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
6610: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
6620: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
6630: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
6640: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
6650: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
6660: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
6670: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6680: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
6690: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
66a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
66b0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
66c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
66d0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
66e0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
66f0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6700: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6710: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
6720: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6730: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
6740: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
6750: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
6760: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
6770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
6780: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
6790: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
67a0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
67b0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
67c0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
67d0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
67e0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
67f0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
6800: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
6810: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
6820: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
6830: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
6840: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
6850: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
6860: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
6870: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
6880: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
6890: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
68a0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
68b0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
68c0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
68d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
68e0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
68f0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
6900: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
6910: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6920: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
6930: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
6940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
6950: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
6960: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
6970: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6980: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
6990: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
69a0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
69b0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
69c0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
69d0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
69e0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
69f0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6a00: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6a10: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6a20: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6a30: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6a40: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6a50: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6a60: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6a70: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
6a80: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6a90: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6aa0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6ab0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6ac0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6ad0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6ae0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6af0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6b00: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
6b10: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
6b20: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
6b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6b40: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
6b50: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
6b60: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
6b70: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
6b80: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
6b90: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
6ba0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6bb0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
6bc0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
6bd0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
6be0: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
6bf0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
6c00: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
6c10: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
6c20: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
6c30: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
6c40: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
6c50: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
6c60: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
6c70: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
6c80: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
6c90: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
6ca0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
6cb0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
6cc0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6cd0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
6ce0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
6cf0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
6d00: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
6d10: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
6d20: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
6d30: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6d40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6d70: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
6d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6d90: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6da0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6db0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6dd0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6de0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
6df0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6e00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6e10: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
6e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e30: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
6e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e50: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
6e60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6e70: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
6e80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
6e90: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
6ea0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
6eb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ec0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6ed0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6ee0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6ef0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f10: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
6f20: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6f30: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6f40: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6f50: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6f60: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6f70: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6f80: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6f90: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6fa0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6fb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6fc0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6fd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6fe0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6ff0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
7000: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
7010: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
7020: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
7030: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
7040: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
7050: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
7060: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
7070: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
7080: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7090: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
70a0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
70b0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
70c0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
70d0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
70e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
70f0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
7100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
7110: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
7120: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
7130: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
7140: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
7150: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
7160: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
7170: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7180: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
7190: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
71a0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
71b0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
71c0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
71d0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
71e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
71f0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
7200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7210: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
7220: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
7230: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7240: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
7250: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
7260: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
7270: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7280: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7290: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
72a0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
72b0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
72c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
72d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
72e0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
72f0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7300: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7310: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
7320: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
7340: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
7350: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
7360: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
7370: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
7380: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7390: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
73a0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
73b0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
73c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
73d0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
73e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
73f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
7400: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
7410: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7420: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
7430: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
7440: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7450: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
7460: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
7470: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
7480: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7490: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
74a0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
74b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
74c0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
74d0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
74e0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
74f0: 2a 78 53 68 6d 4f 70 65 6e 29 28 73 71 6c 69 74  *xShmOpen)(sqlit
7500: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7510: 20 28 2a 78 53 68 6d 53 69 7a 65 29 28 73 71 6c   (*xShmSize)(sql
7520: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7530: 72 65 71 53 69 7a 65 2c 20 69 6e 74 20 2a 70 4e  reqSize, int *pN
7540: 65 77 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  ewSize);.  int (
7550: 2a 78 53 68 6d 47 65 74 29 28 73 71 6c 69 74 65  *xShmGet)(sqlite
7560: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 72 65 71  3_file*, int req
7570: 53 69 7a 65 2c 20 69 6e 74 20 2a 70 53 69 7a 65  Size, int *pSize
7580: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
7590: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
75a0: 52 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33  Release)(sqlite3
75b0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
75c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
75d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
75e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
75f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7600: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7620: 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f 73 65   int (*xShmClose
7630: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7640: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7650: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 61  ;.  int (*xShmPa
7660: 67 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ge)(sqlite3_file
7670: 2a 2c 20 69 6e 74 20 69 50 61 67 65 2c 20 69 6e  *, int iPage, in
7680: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
7690: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
76a0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
76b0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
76c0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
76d0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
76e0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
76f0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7700: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7710: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7720: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7730: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7740: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7750: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7760: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7770: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7780: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7790: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
77a0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
77b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
77c0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
77d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
77e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
77f0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7800: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7810: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7820: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7830: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7840: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7850: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7860: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7870: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7880: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7890: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
78a0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
78b0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
78c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
78d0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
78e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
78f0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7900: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7910: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7920: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7930: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7940: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7950: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7960: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7970: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7980: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
79a0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
79b0: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
79c0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
79d0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
79e0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
79f0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7a00: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7a10: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7a20: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7a30: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7a40: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7a50: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7a60: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7a70: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7a80: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7a90: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7aa0: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7ab0: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7ac0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7ad0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7ae0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7af0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7b00: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7b10: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2f 0a 23 64  un faster..*/.#d
7b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
7b30: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
7b40: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
7b50: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
7b60: 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64  XYFILE      2.#d
7b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
7b80: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
7b90: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7ba0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
7bb0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
7bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
7bd0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
7be0: 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      5../*.** CAP
7bf0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
7c00: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
7c10: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
7c20: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
7c30: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7c40: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
7c50: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
7c60: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
7c70: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
7c80: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
7c90: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
7ca0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
7cb0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
7cc0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
7cd0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
7ce0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
7cf0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
7d00: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
7d10: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
7d20: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
7d30: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
7d40: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7d50: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
7d60: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
7d70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7d80: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
7d90: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7da0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7db0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7dc0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7dd0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7de0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7df0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7e00: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7e10: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7e20: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7e30: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7e40: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7e50: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7e60: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7e70: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7e80: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7e90: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7ea0: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7ec0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7ed0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7ee0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7ef0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7f00: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7f10: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7f20: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7f30: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7f40: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7f50: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7f60: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7f70: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7f80: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7f90: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7fa0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7fb0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7fc0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7fd0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7fe0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7ff0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
8000: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
8010: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
8020: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
8030: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
8040: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
8050: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
8060: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
8070: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
8080: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
8090: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
80a0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
80b0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
80c0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
80d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
80e0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
80f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8100: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8110: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8120: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8130: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
8140: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
8150: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
8160: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
8170: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
8180: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
8190: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
81a0: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
81b0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
81c0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
81d0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
81e0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
81f0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8200: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8210: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8220: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8230: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
8240: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
8250: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
8260: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
8270: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
8280: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
8290: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
82a0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
82b0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
82c0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
82d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
82e0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
82f0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8300: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8310: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8320: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8330: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
8340: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
8350: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
8360: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
8370: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
8380: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
8390: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
83a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
83b0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
83c0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
83d0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
83e0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
83f0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8400: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8410: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8420: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8430: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
8440: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
8450: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
8460: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
8470: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
8480: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
8490: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
84a0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
84b0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
84c0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
84d0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
84e0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
84f0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8500: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8510: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8520: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
8530: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
8540: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
8550: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
8560: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
8570: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
8580: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
8590: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
85a0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
85b0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
85c0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
85d0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
85e0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
85f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8600: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8610: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8620: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8630: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
8640: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
8650: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8660: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
8670: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
8680: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
8690: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
86a0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
86b0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
86c0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
86d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
86e0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
86f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8700: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
8710: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8720: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8730: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
8740: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
8750: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
8760: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
8770: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
8780: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8790: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
87a0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
87b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
87c0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
87d0: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
87e0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
87f0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
8800: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8810: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8820: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8830: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
8840: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
8850: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8860: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
8870: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8880: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
8890: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
88a0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
88b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
88c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
88d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
88e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
88f0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
8900: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ul>.**.** The f
8910: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
8920: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
8930: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
8940: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
8950: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
8960: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
8970: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
8980: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
8990: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
89a0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
89b0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
89c0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
89d0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
89e0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
89f0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8a00: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
8a10: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
8a20: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
8a30: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
8a40: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
8a50: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
8a60: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
8a70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
8a80: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
8a90: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8aa0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8ab0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8ac0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8ad0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8ae0: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8af0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8b00: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8b10: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8b20: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8b30: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8b40: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8b50: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8b60: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8b70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8b80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8b90: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8ba0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8bb0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8bc0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8bd0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8be0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8bf0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8c00: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8c10: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8c20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8c30: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
8c40: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
8c50: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
8c60: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
8c70: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
8c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8c90: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8ca0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
8cb0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
8cc0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
8cd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8ce0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
8cf0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
8d00: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
8d10: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
8d20: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
8d30: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
8d40: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
8d50: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
8d60: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
8d70: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
8d80: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
8d90: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
8da0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
8db0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
8dc0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
8dd0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
8de0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
8df0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
8e00: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
8e10: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
8e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
8e30: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
8e40: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
8e50: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
8e60: 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73 7a  *.** At least sz
8e70: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
8e80: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
8e90: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
8ea0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
8eb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
8ec0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
8ed0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
8ee0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8ef0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
8f00: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
8f10: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
8f20: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
8f30: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
8f40: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
8f50: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
8f60: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
8f70: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
8f80: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
8f90: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
8fa0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
8fb0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
8fc0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
8fd0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
8fe0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
8ff0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
9000: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
9010: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9020: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
9030: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
9040: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
9050: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
9060: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
9070: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
9080: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
9090: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
90a0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
90b0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
90c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
90d0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
90e0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
90f0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
9100: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9110: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
9120: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
9130: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
9140: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
9150: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
9160: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
9170: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
9180: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
9190: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
91a0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
91b0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ctory..**.** SQL
91c0: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
91d0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
91e0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
91f0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
9200: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
9210: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
9220: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
9230: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
9240: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
9250: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
9260: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
9270: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
9280: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
9290: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
92a0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
92b0: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
92c0: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
92d0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
92e0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
92f0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
9300: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
9310: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
9320: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
9330: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
9340: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
9350: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
9360: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
9370: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9380: 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20  , xSleep(), and 
9390: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
93a0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
93b0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
93c0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
93d0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
93e0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
93f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9400: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9410: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9420: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9430: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9440: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9450: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9460: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9470: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9480: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
9490: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
94a0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
94b0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
94c0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
94d0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
94e0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
94f0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9500: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9510: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9520: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9530: 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72  iven.  The xCurr
9540: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
9550: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
9560: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
9570: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
9580: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a  date and time..*
9590: 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  *.*/.typedef str
95a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
95b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
95c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
95d0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
95e0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
95f0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
9600: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
9610: 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 2) */.  int 
9620: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
9630: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
9640: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
9650: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
9660: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
9670: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
9680: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
9690: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
96a0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
96b0: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
96c0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
96d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
96e0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
96f0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
9700: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
9710: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
9720: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
9730: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
9740: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
9750: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
9760: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
9770: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9780: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
9790: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
97a0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
97b0: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
97c0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
97d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
97e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
97f0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
9800: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
9810: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9820: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9830: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
9840: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
9850: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
9860: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9870: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9880: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
9890: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
98a0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
98b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
98c0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
98d0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
98e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
98f0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
9900: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
9910: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
9920: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
9930: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
9940: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
9950: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
9960: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
9970: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
9980: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
9990: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
99a0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
99b0: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
99c0: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
99d0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
99e0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
99f0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
9a00: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
9a10: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
9a20: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
9a30: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
9a40: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
9a50: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
9a60: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
9a70: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
9a80: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
9a90: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
9aa0: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
9ab0: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
9ac0: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
9ad0: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
9ae0: 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
9af0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9b00: 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74 20  ar *zOld, const 
9b10: 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e 74 20  char *zNew, int 
9b20: 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e 74 20  dirSync);.  int 
9b30: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
9b40: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
9b50: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9b60: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
9b70: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
9b80: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
9b90: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
9ba0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
9bb0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
9bc0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
9bd0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
9be0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
9bf0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
9c00: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
9c10: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
9c20: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
9c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9c40: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9c50: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9c60: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9c70: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9c80: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9c90: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9ca0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
9cb0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
9cc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9cd0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
9ce0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
9cf0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
9d00: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9d10: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9d20: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
9d30: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
9d40: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9d50: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9d60: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9d70: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9d80: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9d90: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9da0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9db0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9dc0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9dd0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9de0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
9df0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9e00: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
9e10: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9e20: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9e30: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
9e40: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9e50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9e60: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9e70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9e80: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9e90: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9ea0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
9eb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9ec0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
9ed0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
9ee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
9ef0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
9f00: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
9f10: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
9f20: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
9f30: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
9f40: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
9f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
9f60: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
9f70: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
9f80: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
9f90: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
9fa0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
9fb0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
9fc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
9fd0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
9fe0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
9ff0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a000: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
a010: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
a020: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a030: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
a040: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
a050: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
a060: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
a070: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
a080: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
a090: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
a0a0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
a0b0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
a0c0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
a0d0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
a0e0: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
a0f0: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
a100: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
a110: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
a120: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
a130: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
a140: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
a150: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
a160: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
a170: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
a180: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
a190: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
a1a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a1b0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
a1c0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
a1d0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
a1e0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a1f0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
a200: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
a210: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a220: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
a230: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
a240: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
a250: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
a260: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
a270: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a280: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
a290: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
a2a0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
a2b0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
a2c0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
a2d0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
a2e0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
a2f0: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
a300: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
a310: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
a320: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
a330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a340: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
a350: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
a360: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
a370: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
a380: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a390: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a3a0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
a3b0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
a3c0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
a3d0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
a3e0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
a3f0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
a400: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
a410: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
a420: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a430: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
a440: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
a450: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
a460: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
a470: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
a480: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
a490: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
a4a0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
a4b0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
a4c0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
a4d0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
a4e0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
a4f0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
a500: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
a510: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a520: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
a530: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
a540: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
a550: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
a560: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
a570: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
a580: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
a590: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
a5a0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
a5b0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
a5c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
a5d0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
a5e0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
a5f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a600: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
a610: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
a620: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
a630: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
a640: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
a650: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
a660: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
a670: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
a680: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
a690: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
a6a0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
a6b0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
a6c0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
a6d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
a6e0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
a6f0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
a700: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
a710: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
a720: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
a730: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
a740: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
a750: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
a760: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
a770: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
a780: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
a790: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
a7a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a7b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
a7c0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
a7d0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
a7e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
a7f0: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
a800: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a810: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
a820: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
a830: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
a840: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
a850: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
a860: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
a870: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
a880: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
a890: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
a8a0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
a8b0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
a8c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
a8d0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
a8e0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
a8f0: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
a900: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
a910: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
a920: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
a930: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
a940: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
a950: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
a960: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
a970: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
a980: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
a990: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
a9a0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
a9b0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
a9c0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
a9d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a9e0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
a9f0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
aa00: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
aa10: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
aa20: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
aa30: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
aa40: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
aa50: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
aa60: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
aa70: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aa80: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
aa90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aaa0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
aab0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
aac0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
aad0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
aae0: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
aaf0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
ab00: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
ab10: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
ab20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ab30: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
ab40: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
ab50: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
ab60: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
ab70: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
ab80: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
ab90: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
aba0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
abb0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
abc0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
abd0: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
abe0: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
abf0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
ac00: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
ac10: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ac20: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
ac30: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
ac40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
ac50: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
ac60: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
ac70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ac80: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
ac90: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
aca0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
acb0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
acc0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
acd0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
ace0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
acf0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
ad00: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
ad10: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
ad20: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
ad30: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
ad40: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
ad50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ad60: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
ad70: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ad80: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ad90: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
ada0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
adb0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
adc0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
add0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
ade0: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
adf0: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
ae00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ae10: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
ae20: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
ae30: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
ae40: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
ae50: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
ae60: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ae70: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ae80: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
ae90: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
aea0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
aeb0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
aec0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
aed0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
aee0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
aef0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
af00: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
af10: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
af20: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
af30: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
af40: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
af50: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
af60: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
af70: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
af80: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
af90: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
afa0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
afb0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
afc0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
afd0: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
afe0: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
aff0: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
b000: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
b010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b020: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
b030: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
b040: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
b050: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
b060: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
b070: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
b080: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
b090: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
b0a0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
b0b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b0c0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
b0d0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
b0e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b0f0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
b100: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
b110: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
b120: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
b130: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
b140: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
b150: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
b160: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
b170: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
b180: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
b190: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
b1a0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
b1b0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
b1c0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
b1d0: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
b1e0: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
b1f0: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
b200: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
b210: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
b220: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
b230: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
b240: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
b250: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
b260: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
b270: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
b280: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
b290: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b2a0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
b2b0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
b2c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
b2d0: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
b2e0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
b2f0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
b300: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
b310: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b320: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
b330: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
b340: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
b350: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
b360: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
b370: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
b380: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b390: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
b3a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
b3b0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
b3c0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
b3d0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
b3e0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
b3f0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
b400: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
b410: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
b420: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
b430: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
b440: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
b450: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
b460: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
b470: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
b480: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
b490: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
b4a0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
b4b0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
b4c0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
b4d0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
b4e0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
b4f0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
b500: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
b510: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
b520: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
b530: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
b540: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
b550: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
b560: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
b570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
b580: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
b590: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
b5a0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
b5b0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
b5c0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
b5d0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
b5e0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
b5f0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
b600: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
b610: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b620: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
b630: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
b640: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
b650: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
b660: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
b670: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
b680: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
b690: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b6a0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
b6b0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
b6c0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
b6d0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
b6e0: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
b6f0: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
b700: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
b710: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
b720: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
b730: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
b740: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
b750: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
b760: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
b770: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
b780: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
b790: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
b7a0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
b7b0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
b7c0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
b7d0: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
b7e0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
b7f0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
b800: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
b810: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
b820: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
b830: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
b840: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
b850: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
b860: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
b870: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
b880: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
b890: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
b8a0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
b8b0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
b8c0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
b8d0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
b8e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
b8f0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
b900: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
b910: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
b920: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
b930: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
b940: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
b950: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
b960: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
b970: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
b980: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
b990: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
b9a0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
b9b0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
b9c0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
b9d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
b9e0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
b9f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
ba00: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
ba10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ba20: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
ba30: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ba40: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
ba50: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
ba60: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
ba70: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
ba80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
ba90: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
baa0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
bab0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
bac0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
bad0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
bae0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
baf0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
bb00: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
bb10: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
bb20: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
bb30: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
bb40: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
bb50: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
bb60: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
bb70: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
bb80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
bb90: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
bba0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
bbb0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
bbc0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
bbd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
bbe0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
bbf0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
bc00: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
bc10: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
bc20: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
bc30: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
bc40: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
bc50: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
bc60: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
bc70: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bc80: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
bc90: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
bca0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
bcb0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
bcc0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
bcd0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
bce0: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
bcf0: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
bd00: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
bd10: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
bd20: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
bd30: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
bd40: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
bd50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
bd60: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
bd70: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
bd80: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
bd90: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
bda0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
bdb0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
bdc0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
bdd0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
bde0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
bdf0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
be00: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
be10: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
be20: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
be30: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
be40: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
be50: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
be60: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
be70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
be80: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
be90: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
bea0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
beb0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
bec0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
bed0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
bee0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
bef0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
bf00: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
bf10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
bf20: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
bf30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
bf40: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
bf50: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
bf60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
bf70: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
bf80: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
bf90: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
bfa0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
bfb0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
bfc0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
bfd0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
bfe0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
bff0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
c000: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
c010: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
c020: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
c030: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
c040: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
c050: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
c060: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
c070: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
c080: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
c090: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
c0a0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
c0b0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
c0c0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
c0d0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
c0e0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
c0f0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
c100: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c110: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
c120: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
c130: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
c140: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
c150: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
c160: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
c170: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c180: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
c190: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
c1a0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
c1b0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
c1c0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
c1d0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
c1e0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
c1f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
c200: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
c210: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
c220: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
c230: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
c240: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
c250: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
c260: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
c270: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
c280: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
c290: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
c2a0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
c2b0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
c2c0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
c2d0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
c2e0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
c2f0: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
c300: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
c310: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
c320: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
c330: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
c340: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
c350: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
c360: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c370: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
c380: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
c390: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
c3a0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
c3b0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
c3c0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
c3d0: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
c3e0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c3f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c400: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
c410: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
c420: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
c430: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
c440: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
c450: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
c460: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
c470: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
c480: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
c490: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
c4a0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
c4b0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
c4c0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
c4d0: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
c4e0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
c4f0: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
c500: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
c510: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
c520: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
c530: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
c540: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
c550: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
c560: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
c570: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
c580: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
c590: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
c5a0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
c5b0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
c5c0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
c5d0: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
c5e0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
c5f0: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
c600: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
c610: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
c620: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
c630: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
c640: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
c650: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
c660: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
c670: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
c680: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
c690: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
c6a0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
c6b0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
c6c0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
c6d0: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
c6e0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
c6f0: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
c700: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
c710: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
c720: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
c730: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
c740: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
c750: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
c760: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
c770: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
c780: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
c790: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
c7a0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
c7b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
c7c0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
c7d0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
c7e0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
c7f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
c800: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
c810: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
c820: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
c830: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
c840: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
c850: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
c860: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
c870: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
c880: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
c890: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
c8a0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
c8b0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
c8c0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
c8d0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
c8e0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
c8f0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
c900: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
c910: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
c920: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
c930: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
c940: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
c950: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
c960: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
c970: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
c980: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
c990: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
c9a0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
c9b0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
c9c0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
c9d0: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
c9e0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
c9f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ca00: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
ca10: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
ca20: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
ca30: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
ca40: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
ca50: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
ca60: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
ca70: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
ca80: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
ca90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
caa0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
cab0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cac0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
cad0: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
cae0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
caf0: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
cb00: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
cb10: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
cb20: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
cb30: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
cb40: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
cb50: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
cb60: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
cb70: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
cb80: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
cb90: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
cba0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
cbb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
cbc0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cbd0: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
cbe0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
cbf0: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
cc00: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
cc10: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
cc20: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
cc30: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
cc40: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
cc50: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
cc60: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
cc70: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
cc80: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
cc90: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
cca0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
ccb0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
ccc0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
ccd0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
cce0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
ccf0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
cd00: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
cd10: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
cd20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
cd30: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
cd40: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
cd50: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
cd60: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
cd70: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
cd80: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
cd90: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
cda0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
cdb0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
cdc0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
cdd0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
cde0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
cdf0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
ce00: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
ce10: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
ce20: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
ce30: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
ce40: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
ce50: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
ce60: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
ce70: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
ce80: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
ce90: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
cea0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ceb0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
cec0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
ced0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
cee0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
cef0: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
cf00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cf10: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
cf20: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
cf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
cf40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
cf50: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
cf60: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
cf70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cf80: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
cf90: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
cfa0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
cfb0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
cfc0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
cfd0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
cfe0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
cff0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
d000: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
d010: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
d020: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
d030: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
d040: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
d050: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
d060: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d070: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
d080: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
d090: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
d0a0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
d0b0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
d0c0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d0d0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
d0e0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
d0f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d100: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
d110: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d120: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d130: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d140: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d150: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d160: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d170: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
d180: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d190: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
d1a0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
d1b0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
d1c0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
d1d0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
d1e0: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
d1f0: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
d200: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d210: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d220: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d230: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d240: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d250: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d260: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d270: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
d280: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
d290: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
d2a0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
d2b0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
d2c0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
d2d0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
d2e0: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
d2f0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d300: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
d310: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
d320: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
d330: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d340: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d350: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d360: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
d370: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d380: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d390: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d3a0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d3b0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d3c0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
d3d0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
d3e0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
d3f0: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
d400: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d410: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d420: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d430: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
d440: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
d450: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
d460: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
d470: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
d480: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d490: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d4a0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
d4b0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
d4c0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
d4d0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
d4e0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
d4f0: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
d500: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
d510: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
d520: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
d530: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
d540: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
d550: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d560: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
d570: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
d580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d590: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
d5a0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
d5b0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
d5c0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
d5d0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
d5e0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
d5f0: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
d600: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
d610: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
d620: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d630: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
d640: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
d650: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
d660: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
d670: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
d680: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d690: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
d6a0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d6b0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
d6c0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
d6d0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
d6e0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
d6f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
d700: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
d710: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
d720: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
d730: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
d740: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
d750: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
d760: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
d770: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
d780: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d790: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
d7a0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d7b0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
d7c0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
d7d0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
d7e0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
d7f0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
d800: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
d810: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
d820: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
d830: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
d840: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
d850: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d860: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
d870: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
d880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
d890: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
d8a0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
d8b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d8c0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
d8d0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
d8e0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
d8f0: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
d900: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
d910: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
d920: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
d930: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
d940: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
d950: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
d960: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
d970: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
d980: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
d990: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
d9a0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
d9b0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
d9c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d9d0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
d9e0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
d9f0: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
da00: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
da10: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
da20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
da30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
da40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
da50: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
da60: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
da70: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
da80: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
da90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
daa0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dab0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dac0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dad0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
dae0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
daf0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
db00: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
db10: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
db20: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
db30: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
db40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
db50: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
db60: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
db70: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
db80: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
db90: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
dba0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
dbb0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
dbc0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
dbd0: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
dbe0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
dbf0: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
dc00: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dc10: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
dc20: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
dc30: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
dc40: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
dc50: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
dc60: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
dc70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
dc80: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
dc90: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
dca0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
dcb0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
dcc0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
dcd0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
dce0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
dcf0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
dd00: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
dd10: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
dd20: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
dd30: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
dd40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dd50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
dd60: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
dd70: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
dd80: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
dd90: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
dda0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
ddb0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
ddc0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
ddd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
dde0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
ddf0: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
de00: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
de10: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
de20: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
de30: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
de40: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
de50: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
de60: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
de70: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
de80: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
de90: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
dea0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
deb0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
dec0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
ded0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
dee0: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
def0: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
df00: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
df10: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
df20: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
df30: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
df40: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
df50: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
df60: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
df70: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
df80: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
df90: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
dfa0: 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
dfb0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
dfc0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
dfd0: 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
dfe0: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
dff0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
e000: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
e010: 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
e020: 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
e030: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
e040: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
e050: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
e060: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
e070: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e080: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
e090: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
e0a0: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
e0b0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
e0c0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
e0d0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
e0e0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
e0f0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
e100: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
e110: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
e120: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
e130: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
e140: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c  ch the scrach al
e150: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
e160: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
e170: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
e180: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
e190: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
e1a0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e1b0: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
e1c0: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
e1d0: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
e1e0: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
e1f0: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a  le of 16. The sz
e200: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
e210: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73  d be a few bytes
e220: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20  .** larger than 
e230: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74  the actual scrat
e240: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ch space require
e250: 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61  d due to interna
e260: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54  l overhead..** T
e270: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e280: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
e290: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
e2a0: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
e2b0: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
e2c0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
e2d0: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
e2e0: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
e2f0: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
e300: 68 20 62 75 66 66 65 72 20 70 65 72 20 74 68 72  h buffer per thr
e310: 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
e320: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
e330: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
e340: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
e350: 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20  reads.  ^SQLite 
e360: 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65  will.** never re
e370: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
e380: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
e390: 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73  ore than 6 times
e3a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
e3b0: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
e3c0: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
e3d0: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63  ds additional sc
e3e0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
e3f0: 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20  ond .** what is 
e400: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
e410: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e420: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
e430: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
e440: 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
e450: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
e460: 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
e470: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e480: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
e490: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
e4a0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
e4b0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
e4c0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
e4d0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
e4e0: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
e4f0: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
e500: 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
e510: 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
e520: 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a  plemenation.  .*
e530: 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
e540: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
e550: 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
e560: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
e570: 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
e580: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
e590: 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
e5a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e5b0: 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
e5c0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
e5d0: 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
e5e0: 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
e5f0: 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
e600: 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
e610: 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
e620: 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
e630: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
e640: 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
e650: 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
e660: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
e670: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
e680: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
e690: 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
e6a0: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
e6b0: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
e6c0: 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
e6d0: 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
e6e0: 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
e6f0: 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
e700: 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
e710: 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
e720: 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
e730: 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
e740: 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
e750: 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
e760: 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
e770: 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
e780: 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
e790: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
e7a0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
e7b0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
e7c0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
e7d0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
e7e0: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
e7f0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
e800: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
e810: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e820: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
e830: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
e840: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
e850: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
e860: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
e870: 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
e880: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
e890: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
e8a0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
e8b0: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
e8c0: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
e8d0: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
e8e0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e8f0: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
e900: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
e910: 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65  e..** ^The imple
e920: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
e930: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
e940: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
e950: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
e960: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
e970: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
e980: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
e990: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
e9a0: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
e9b0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
e9c0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e9d0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e9e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
e9f0: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
ea00: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ea10: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
ea20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ea30: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
ea40: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
ea50: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
ea60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
ea70: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
ea80: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
ea90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
eaa0: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
eab0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
eac0: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
ead0: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
eae0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
eaf0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
eb00: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
eb10: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
eb20: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
eb30: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
eb40: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
eb50: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
eb60: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
eb70: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
eb80: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
eb90: 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
eba0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
ebb0: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
ebc0: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
ebd0: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
ebe0: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
ebf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ec00: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
ec10: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
ec20: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
ec30: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
ec40: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
ec50: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
ec60: 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
ec70: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
ec80: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
ec90: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
eca0: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
ecb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
ecc0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
ecd0: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
ece0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
ecf0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
ed00: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
ed10: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
ed20: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
ed30: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
ed40: 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
ed50: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
ed60: 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
ed70: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
ed80: 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
ed90: 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
eda0: 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
edb0: 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
edc0: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
edd0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ede0: 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
edf0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
ee00: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
ee10: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ee20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ee30: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
ee40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
ee50: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
ee60: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
ee70: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
ee80: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
ee90: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
eea0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
eeb0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
eec0: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
eed0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
eee0: 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
eef0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
ef00: 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
ef10: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
ef20: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
ef30: 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
ef40: 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
ef50: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ef60: 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
ef70: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ef80: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ef90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
efa0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
efb0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
efc0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
efd0: 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
efe0: 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
eff0: 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
f000: 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
f010: 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
f020: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f030: 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
f040: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f050: 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
f060: 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
f070: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
f080: 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
f090: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f0a0: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
f0b0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f0c0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f0d0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f0e0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f0f0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
f100: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
f110: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f120: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
f130: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
f140: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
f150: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
f160: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
f170: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
f180: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
f190: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
f1a0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
f1b0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
f1c0: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
f1d0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
f1e0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
f1f0: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
f200: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
f210: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
f220: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
f230: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
f240: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
f250: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
f260: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
f270: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
f280: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
f290: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f2a0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
f2b0: 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
f2c0: 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
f2d0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
f2e0: 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
f2f0: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
f300: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f310: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
f320: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
f330: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f340: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
f350: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f360: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
f370: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
f380: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
f390: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
f3a0: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
f3b0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
f3c0: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
f3d0: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
f3e0: 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
f3f0: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
f400: 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
f410: 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
f420: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
f430: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f440: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
f450: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
f460: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
f470: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
f480: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
f490: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
f4a0: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
f4b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
f4c0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
f4d0: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
f4e0: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
f4f0: 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
f500: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f510: 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
f520: 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
f530: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
f540: 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
f550: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
f560: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
f570: 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
f580: 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
f590: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f5a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f5b0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
f5c0: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
f5d0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
f5e0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
f5f0: 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
f600: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
f610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
f620: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
f630: 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
f640: 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
f650: 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
f660: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
f670: 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
f680: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
f690: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
f6a0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
f6b0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
f6c0: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
f6d0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f6e0: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c  ONFIG_GETPCACHE<
f6f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f700: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f710: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f720: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f730: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
f740: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f750: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f760: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
f770: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
f780: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
f790: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
f7a0: 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
f7b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
f7c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f7d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f7e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
f7f0: 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
f800: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
f810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
f820: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
f830: 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
f840: 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
f850: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
f860: 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
f870: 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
f880: 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
f890: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
f8a0: 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
f8b0: 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
f8c0: 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
f8d0: 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
f8e0: 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
f8f0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
f900: 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
f910: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
f920: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
f930: 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
f940: 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
f950: 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
f960: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f970: 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
f980: 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
f990: 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
f9a0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f9b0: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
f9c0: 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
f9d0: 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
f9e0: 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
f9f0: 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
fa00: 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
fa10: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
fa20: 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
fa30: 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
fa40: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
fa50: 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
fa60: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
fa70: 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
fa80: 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
fa90: 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
faa0: 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
fab0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fac0: 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
fad0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
fae0: 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
faf0: 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
fb00: 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
fb10: 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
fb20: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
fb30: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
fb40: 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
fb50: 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
fb60: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
fb70: 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
fb80: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
fb90: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
fba0: 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
fbb0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
fbc0: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
fbd0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
fbe0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
fbf0: 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
fc00: 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
fc10: 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
fc20: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
fc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fc40: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
fc50: 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
fc60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fc70: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
fc80: 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
fc90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fca0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
fcb0: 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
fcc0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
fcd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
fce0: 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
fcf0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
fd00: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
fd10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
fd20: 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
fd30: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
fd40: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
fd50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
fd60: 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
fd70: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
fd80: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
fd90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
fda0: 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
fdb0: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
fdc0: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
fdd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
fde0: 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
fdf0: 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
fe00: 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
fe10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fe20: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
fe30: 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
fe40: 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
fe50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
fe60: 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
fe70: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
fe80: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
fe90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
fea0: 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
feb0: 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
fec0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
fed0: 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
fee0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
fef0: 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
ff00: 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
ff10: 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
ff20: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
ff30: 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
ff40: 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
ff50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
ff60: 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
ff70: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
ff80: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
ff90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
ffa0: 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
ffb0: 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   15  /* sqlite3_
ffc0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
ffd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ffe0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
fff0: 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
10000 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a  nc, void* */../*
10010 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
10020 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
10030 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
10040 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
10050 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
10060 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
10070 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
10080 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
10090 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
100a0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
100b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
100c0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
100d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
100e0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
100f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10100 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
10110 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
10120 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
10130 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
10140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10150 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
10160 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
10170 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
10180 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
10190 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
101a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
101b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
101c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
101d0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
101e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
101f0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
10200 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
10210 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10220 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
10230 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
10240 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
10250 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
10260 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
10270 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
10280 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10290 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
102a0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
102b0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
102c0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
102d0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
102e0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
102f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10300 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
10310 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
10320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
10330 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
10340 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
10350 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
10360 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10370 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
10380 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72  nter to an memor
10390 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
103a0 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
103b0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
103c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
103d0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
103e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
103f0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
10400 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
10410 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
10420 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
10430 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
10440 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
10450 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
10460 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
10470 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
10480 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
10490 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
104a0 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
104b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
104c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
104d0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
104e0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
104f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10500 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
10510 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
10520 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
10530 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
10540 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
10550 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
10560 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
10570 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
10580 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
10590 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
105a0 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
105b0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
105c0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
105d0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
105e0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
105f0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
10600 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
10610 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  .** multiple of 
10620 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  8.  See also: [S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10640 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a  KASIDE]</dd>.**.
10650 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
10660 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
10670 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
10680 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
10690 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
106a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
106b0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
106c0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
106d0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
106e0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
106f0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
10700 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
10710 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
10720 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
10730 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
10740 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
10750 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
10760 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
10770 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10780 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
10790 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
107a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
107b0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
107c0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
107d0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
107e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
107f0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
10800 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
10810 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
10820 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
10830 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
10840 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
10850 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
10860 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
10870 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
10880 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
10890 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
108a0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
108b0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
108c0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
108d0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
108e0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
108f0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
10900 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
10910 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
10920 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
10930 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
10940 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
10950 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
10960 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
10970 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
10980 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
10990 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
109a0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
109b0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
109c0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
109d0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
109e0 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
109f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10a00 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10a10 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  st argument.  ^I
10a20 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
10a30 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
10a40 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
10a50 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
10a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
10a70 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
10a80 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
10a90 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
10aa0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
10ab0 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
10ac0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
10ad0 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10ae0 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10af0 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
10b00 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
10b10 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
10b20 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
10b30 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
10b40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10b50 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10b60 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10b70 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
10b80 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
10b90 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a  igger fired.)^.*
10ba0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
10bb0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
10bc0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
10bd0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
10be0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
10bf0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
10c00 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
10c10 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
10c20 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
10c30 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
10c40 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
10c50 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
10c60 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
10c70 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
10c80 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
10c90 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
10ca0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
10cb0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
10cc0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
10cd0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
10ce0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
10cf0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
10d00 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
10d10 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
10d20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
10d30 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
10d40 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
10d50 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
10d60 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
10d70 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
10d80 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
10d90 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
10da0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
10db0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
10dc0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
10dd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
10de0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
10df0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
10e00 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
10e10 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
10e20 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
10e30 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
10e40 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
10e50 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
10e60 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
10e70 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
10e80 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
10e90 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
10ea0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10eb0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
10ec0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
10ed0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
10ee0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
10ef0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
10f00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
10f10 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
10f20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
10f30 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10f40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
10f50 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
10f60 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
10f70 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
10f80 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
10f90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10fa0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
10fb0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
10fc0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
10fd0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
10fe0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
10ff0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
11000 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
11010 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
11020 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
11030 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
11040 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
11050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11060 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
11070 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
11080 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
11090 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
110a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
110b0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
110c0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
110d0 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
110e0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
110f0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11100 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
11110 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
11120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11130 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
11140 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11150 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
11160 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
11170 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
11180 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
11190 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
111a0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
111b0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
111c0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
111d0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
111e0 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
111f0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
11200 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
11210 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
11220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
11230 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
11240 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
11250 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
11260 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
11270 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
11280 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
11290 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
112a0 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
112b0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
112c0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
112d0 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
112e0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
112f0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
11300 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
11310 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
11320 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
11330 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
11340 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
11350 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
11360 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
11370 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
11380 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
11390 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
113a0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
113b0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
113c0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
113d0 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
113e0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
113f0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
11400 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
11410 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
11420 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
11430 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
11440 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
11450 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11460 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
11470 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
11480 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
11490 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
114a0 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
114b0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
114c0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
114d0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
114e0 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
114f0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
11500 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
11510 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
11520 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
11530 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
11540 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
11550 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
11560 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
11570 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
11580 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
11590 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
115a0 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
115b0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
115c0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
115d0 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
115e0 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
115f0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
11600 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11610 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
11620 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
11630 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
11640 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
11650 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
11670 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
11680 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
11690 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
116a0 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
116b0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
116c0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
116d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
116e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
116f0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
11700 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
11710 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
11720 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
11730 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11740 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
11750 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
11760 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
11770 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
11780 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
11790 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
117a0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
117b0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
117c0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
117d0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
117e0 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
117f0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
11800 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
11810 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
11820 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
11830 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
11840 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11850 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
11860 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11870 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
11880 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
11890 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
118a0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
118b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
118c0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
118d0 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
118e0 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
118f0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
11900 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
11910 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
11920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11930 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
11940 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
11950 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
11960 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
11970 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
11980 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
11990 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
119a0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
119b0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
119c0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
119d0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
119e0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
119f0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11a00 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
11a10 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
11a20 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
11a30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
11a40 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
11a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11a60 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
11a70 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
11a80 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11a90 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
11aa0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
11ab0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11ac0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
11ad0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
11ae0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
11af0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
11b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
11b10 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
11b20 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
11b30 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
11b40 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
11b50 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
11b60 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
11b70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
11b80 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
11b90 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
11ba0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
11bb0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
11bc0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
11bd0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
11be0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
11bf0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
11c00 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11c10 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
11c20 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
11c30 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
11c40 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
11c50 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
11c60 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
11c70 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
11c80 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
11c90 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
11ca0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
11cb0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
11cc0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
11cd0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
11ce0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
11cf0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
11d00 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
11d10 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11d20 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
11d30 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
11d40 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
11d50 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
11d60 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
11d70 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
11d80 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
11d90 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
11da0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
11db0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
11dc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
11dd0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
11de0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
11df0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
11e00 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
11e10 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
11e20 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
11e30 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
11e40 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
11e50 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
11e60 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
11e70 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
11e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11e90 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
11ea0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11eb0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
11ec0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
11ed0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
11ee0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
11ef0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
11f00 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
11f10 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11f20 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11f30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
11f40 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
11f50 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
11f60 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
11f70 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
11f80 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
11f90 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
11fa0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
11fb0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
11fc0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
11fd0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
11fe0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
11ff0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
12000 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
12010 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
12020 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
12030 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
12040 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
12050 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
12060 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
12070 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
12080 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
12090 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
120a0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
120b0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
120c0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
120d0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
120e0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
120f0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
12100 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
12110 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
12120 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
12130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12140 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
12150 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
12160 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
12170 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12180 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
12190 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
121a0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
121b0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
121c0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
121d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
121e0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
121f0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
12200 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
12210 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
12220 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
12230 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
12240 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
12250 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
12260 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
12270 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
12280 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
12290 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
122a0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
122b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
122c0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
122d0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
122e0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
122f0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12300 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12310 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
12320 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
12330 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
12340 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
12350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
12360 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
12370 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
12380 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
12390 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
123a0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
123b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
123c0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
123d0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
123e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
123f0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12400 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12410 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
12420 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
12430 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
12440 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
12450 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
12460 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
12470 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
12480 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
12490 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
124a0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
124b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
124c0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
124d0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
124e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
124f0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
12500 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
12510 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
12520 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
12530 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
12540 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12550 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
12560 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
12570 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
12580 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
12590 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
125a0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
125b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
125c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
125d0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
125e0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
125f0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
12600 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
12610 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
12620 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
12630 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
12640 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12650 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
12660 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
12670 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
12680 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
12690 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
126a0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
126b0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
126c0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
126d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
126e0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
126f0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
12700 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
12710 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
12720 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
12730 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
12740 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
12750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
12760 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
12770 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
12780 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
12790 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
127a0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
127b0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
127c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
127d0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
127e0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
127f0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
12800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
12810 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
12820 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
12830 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
12840 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
12850 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
12860 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
12870 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
12880 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
12890 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
128a0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
128b0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
128c0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
128d0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
128e0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
128f0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
12900 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
12910 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
12920 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
12930 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
12940 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
12950 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
12960 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
12970 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
12980 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
12990 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
129a0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
129b0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
129c0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
129d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
129e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
129f0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
12a00 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
12a10 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
12a20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12a30 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
12a40 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
12a50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
12a60 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12a70 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12a80 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
12a90 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
12aa0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
12ab0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
12ac0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
12ad0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
12ae0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
12af0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12b00 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
12b10 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
12b20 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
12b30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
12b40 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
12b50 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
12b60 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
12b70 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
12b80 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
12b90 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
12ba0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
12bb0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
12bc0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12bd0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
12be0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
12bf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
12c00 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
12c10 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
12c20 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
12c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12c40 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
12c50 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
12c60 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
12c70 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
12c80 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12c90 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
12ca0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
12cb0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
12cc0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
12cd0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
12ce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
12cf0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
12d00 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
12d10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
12d20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
12d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12d40 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
12d50 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
12d60 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
12d70 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
12d80 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
12d90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
12da0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
12db0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
12dc0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
12dd0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
12de0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
12df0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
12e00 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
12e10 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
12e20 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
12e30 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
12e40 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
12e50 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
12e60 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
12e70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
12e80 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
12e90 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
12ea0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
12eb0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
12ec0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
12ed0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
12ee0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
12ef0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
12f00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
12f10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12f20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12f30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12f40 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
12f50 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
12f60 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
12f70 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
12f80 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
12f90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12fa0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
12fb0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
12fc0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12fd0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
12fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
12ff0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
13000 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
13010 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13020 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
13030 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
13040 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
13050 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
13060 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
13070 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
13080 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
13090 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
130a0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
130b0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
130c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
130d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
130e0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
130f0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
13100 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
13110 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
13120 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
13130 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
13140 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
13150 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
13160 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
13170 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
13180 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
13190 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
131a0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
131b0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
131c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
131d0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
131e0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
131f0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
13200 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
13210 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
13220 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
13230 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13240 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
13250 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
13260 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
13270 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
13280 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
13290 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
132a0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
132b0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
132c0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
132d0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
132e0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
132f0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13300 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
13310 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
13320 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
13330 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
13340 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
13350 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
13360 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
13370 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
13380 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
13390 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
133a0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
133b0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
133c0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
133d0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
133e0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
133f0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
13400 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
13410 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
13420 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
13430 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
13440 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
13450 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
13460 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
13470 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
13480 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
13490 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
134a0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
134b0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
134c0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
134d0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
134e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
134f0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
13500 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
13510 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
13520 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
13530 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
13540 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13550 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
13560 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
13570 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
13580 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
13590 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
135a0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
135b0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
135c0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
135d0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
135e0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
135f0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13600 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13610 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
13620 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
13630 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
13640 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
13650 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
13660 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
13670 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
13680 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
13690 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
136a0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
136b0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
136c0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
136d0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
136e0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
136f0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
13700 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
13710 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
13720 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
13730 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
13740 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
13750 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
13760 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
13770 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13780 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
13790 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
137a0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
137b0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
137c0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
137d0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
137e0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
137f0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
13800 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13810 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13820 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13830 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13840 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13850 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13860 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13870 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
13880 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13890 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
138a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
138b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
138c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
138d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
138e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
138f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
13900 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
13910 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
13920 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
13930 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
13940 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
13950 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
13960 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
13970 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
13980 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
13990 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
139a0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
139b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
139c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
139d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
139e0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
139f0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
13a00 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
13a10 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
13a20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
13a30 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
13a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13a50 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
13a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13a70 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
13a80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
13a90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13aa0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
13ab0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
13ac0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
13ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13ae0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
13af0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
13b00 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
13b10 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13b20 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
13b30 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
13b40 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
13b50 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
13b60 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
13b70 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
13b80 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
13b90 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
13ba0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
13bb0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
13bc0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
13bd0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
13be0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
13bf0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
13c00 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
13c10 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
13c20 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
13c30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
13c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
13c50 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
13c60 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
13c70 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
13c80 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
13c90 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
13ca0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
13cb0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
13cc0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
13cd0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
13ce0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
13cf0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
13d00 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13d10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
13d20 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
13d30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13d40 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
13d50 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
13d60 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
13d70 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
13d80 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
13d90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13da0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
13db0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
13dc0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
13dd0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
13de0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
13df0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13e00 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
13e10 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
13e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13e30 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
13e40 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
13e50 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65  Queries.**.** De
13e60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
13e70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
13e80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
13e90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
13ea0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
13eb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
13ec0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
13ed0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
13ee0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
13ef0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
13f00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
13f10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
13f20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
13f30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
13f40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
13f50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
13f60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
13f70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
13f80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13f90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
13fa0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
13fb0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
13fc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
13fd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
13fe0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
13ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
14000 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
14010 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
14020 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
14030 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
14040 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
14050 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
14060 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
14070 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
14080 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
14090 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
140a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
140b0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
140c0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
140d0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
140e0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
140f0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
14100 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
14110 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
14120 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
14130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
14140 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
14150 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
14160 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
14170 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
14180 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
14190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
141a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
141b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
141c0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
141d0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
141e0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
141f0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
14200 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
14210 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
14220 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
14230 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14240 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
14250 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
14260 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
14270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
14280 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
14290 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
142a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
142b0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
142c0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
142d0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
142e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
142f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
14300 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
14310 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
14320 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14330 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
14340 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
14350 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
14360 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
14370 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
14380 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
14390 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
143a0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
143b0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
143c0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
143d0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
143e0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
143f0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
14400 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
14410 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
14420 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
14430 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
14440 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
14450 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
14460 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
14470 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
14480 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14490 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
144a0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
144b0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
144c0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
144d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
144e0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
144f0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14500 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
14510 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14520 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
14530 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14540 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
14550 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14560 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
14570 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
14580 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
14590 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
145a0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
145b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
145c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
145d0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
145e0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
145f0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
14600 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
14610 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
14620 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14630 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
14640 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
14650 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
14660 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
14670 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
14680 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
14690 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
146a0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
146b0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
146c0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
146d0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
146e0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
146f0 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74  it should pass t
14700 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14710 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
14720 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
14730 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
14740 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
14750 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
14760 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
14770 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
14780 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14790 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
147a0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
147b0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
147c0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
147d0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
147e0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
147f0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
14800 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
14810 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
14820 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
14830 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14840 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
14850 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
14860 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14870 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
14880 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
14890 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
148a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
148b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
148c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
148d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
148e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
148f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
14900 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
14910 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
14920 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
14930 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
14940 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
14950 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
14960 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
14970 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
14980 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
14990 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
149a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
149b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
149c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
149d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
149e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
149f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
14a00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
14a10 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
14a20 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
14a30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
14a40 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
14a50 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
14a60 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
14a70 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
14a80 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
14a90 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
14aa0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
14ab0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
14ac0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
14ad0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
14ae0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
14af0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
14b00 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
14b10 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
14b20 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
14b30 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
14b40 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
14b50 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
14b60 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
14b70 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
14b80 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
14b90 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
14ba0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
14bb0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
14bc0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
14bd0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
14be0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14bf0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
14c00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
14c10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
14c20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
14c30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
14c40 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
14c50 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
14c60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
14c70 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
14c80 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
14c90 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
14ca0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
14cb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
14cc0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
14cd0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
14ce0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
14cf0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
14d00 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
14d10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
14d20 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
14d30 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
14d40 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
14d50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14d60 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
14d70 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
14d80 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
14d90 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
14da0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing..**.** ^(In 
14db0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14dc0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
14dd0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
14de0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
14df0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
14e00 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
14e10 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
14e20 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
14e30 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
14e40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14e50 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
14e60 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
14e70 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
14e80 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
14e90 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
14ea0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
14eb0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
14ec0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
14ed0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
14ee0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
14ef0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
14f00 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
14f10 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
14f20 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
14f30 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
14f40 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
14f50 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
14f60 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f70 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
14f80 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
14f90 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
14fa0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
14fb0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
14fc0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
14fd0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
14fe0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
14ff0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
15000 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
15010 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
15020 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
15030 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
15040 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
15050 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15060 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
15070 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
15080 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
15090 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
150a0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
150b0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
150c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
150d0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
150e0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
150f0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
15100 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
15110 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
15120 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
15130 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
15140 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
15150 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
15160 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
15170 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
15180 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
15190 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
151a0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
151b0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
151c0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
151d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
151e0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
151f0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
15200 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
15210 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
15220 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
15230 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
15240 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
15250 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
15260 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
15270 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
15280 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
15290 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
152a0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
152b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
152c0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
152d0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
152e0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
152f0 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
15300 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
15310 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
15320 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
15330 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
15340 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
15350 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
15360 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
15370 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
15380 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
15390 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
153a0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
153b0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
153c0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
153d0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
153e0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
153f0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
15400 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
15410 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
15420 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
15430 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
15440 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15450 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
15460 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
15470 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
15480 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15490 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
154a0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
154b0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
154c0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
154d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
154e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
154f0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
15500 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
15510 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
15520 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
15530 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
15540 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
15550 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
15560 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
15570 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
15580 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15590 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
155a0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
155b0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
155c0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
155d0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
155e0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
155f0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
15600 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15610 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15620 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
15630 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
15640 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
15650 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15660 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15670 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
15680 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
15690 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
156a0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
156b0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
156c0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
156d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
156e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
156f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15700 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
15710 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
15720 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15730 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
15740 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
15750 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
15760 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
15770 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
15780 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
15790 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
157a0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
157b0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
157c0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
157d0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
157e0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
157f0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
15800 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
15810 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
15820 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
15830 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
15840 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
15850 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
15860 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
15870 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
15880 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
15890 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
158a0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
158b0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
158c0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
158d0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
158e0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
158f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15900 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
15910 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15920 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
15930 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
15940 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
15950 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
15960 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
15970 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
15980 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
15990 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
159a0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
159b0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
159c0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
159d0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
159e0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
159f0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
15a00 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
15a10 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15a20 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
15a30 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
15a40 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
15a50 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
15a60 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
15a70 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
15a80 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
15a90 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
15aa0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
15ab0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
15ac0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
15ad0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
15ae0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
15af0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
15b00 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
15b10 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
15b20 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
15b30 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
15b40 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
15b50 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
15b60 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
15b70 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
15b80 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
15b90 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
15ba0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
15bb0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
15bc0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
15bd0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
15be0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
15bf0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
15c00 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
15c10 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
15c20 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
15c30 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
15c40 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
15c50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
15c60 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
15c70 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
15c80 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
15c90 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
15ca0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
15cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
15cc0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
15cd0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15ce0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
15cf0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
15d00 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
15d10 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
15d20 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
15d30 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
15d40 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
15d50 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
15d60 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
15d70 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
15d80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
15d90 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
15da0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
15db0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
15dc0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
15dd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
15de0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
15df0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
15e00 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
15e10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
15e20 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
15e30 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
15e40 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
15e50 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
15e60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
15e70 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
15e80 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
15e90 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
15ea0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
15eb0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
15ec0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
15ed0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
15ee0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
15ef0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
15f00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
15f10 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
15f20 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
15f30 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
15f40 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
15f50 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
15f60 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
15f70 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
15f80 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
15f90 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
15fa0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
15fb0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
15fc0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
15fd0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
15fe0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
15ff0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
16000 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
16010 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
16020 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
16030 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
16040 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
16050 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
16060 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
16070 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
16080 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
16090 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
160a0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
160b0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
160c0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
160d0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
160e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
160f0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
16100 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
16110 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
16120 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16130 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
16140 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
16150 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
16160 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
16170 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
16180 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
16190 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
161a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
161b0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
161c0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
161d0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
161e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
161f0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
16200 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16220 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
16230 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16240 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16250 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
16260 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
16270 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
16280 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
16290 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
162a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
162b0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
162c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
162d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
162e0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
162f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16300 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
16310 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
16320 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
16330 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
16340 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
16350 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
16360 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
16370 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
16380 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
16390 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
163a0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
163b0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
163c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
163d0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
163e0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
163f0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
16400 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
16410 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
16420 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16430 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
16440 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
16450 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
16460 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
16470 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
16480 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
16490 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
164a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
164b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
164c0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
164d0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
164e0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
164f0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
16500 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  oundary..**.** I
16510 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
16520 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
16530 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
16540 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
16550 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
16560 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
16570 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
16580 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16590 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
165a0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
165b0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
165c0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
165d0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
165e0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
165f0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16600 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16610 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16620 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
16630 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
16640 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
16650 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
16660 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
16670 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
16680 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16690 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
166a0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
166b0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
166c0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
166d0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
166e0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
166f0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16700 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16710 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16720 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
16730 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
16740 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
16750 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
16760 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
16770 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
16780 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16790 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
167a0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
167b0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
167c0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
167d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
167e0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
167f0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16800 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16810 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16820 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
16830 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16840 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
16850 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
16860 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
16870 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
16880 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
16890 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
168a0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
168b0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
168c0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
168d0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
168e0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
168f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16900 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
16910 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
16920 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
16930 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
16940 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
16950 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
16960 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
16970 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
16980 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
16990 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
169a0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
169b0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
169c0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
169d0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
169e0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
169f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
16a00 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
16a10 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
16a20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16a30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
16a40 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
16a50 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
16a60 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
16a70 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
16a80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16a90 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
16aa0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16ab0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
16ac0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
16ad0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
16ae0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
16af0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
16b00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16b10 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
16b20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
16b30 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
16b40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
16b50 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
16b60 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
16b70 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
16b80 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
16b90 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
16ba0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
16bb0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
16bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16bd0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
16be0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
16bf0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
16c00 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
16c10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
16c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16c30 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
16c40 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
16c50 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
16c60 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
16c70 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
16c80 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
16c90 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
16ca0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
16cb0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
16cc0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
16cd0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
16ce0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
16cf0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
16d00 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
16d10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16d20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16d30 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
16d40 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
16d50 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
16d60 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
16d70 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
16d80 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
16d90 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
16da0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
16db0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
16dc0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16dd0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
16de0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
16df0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16e00 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
16e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16e20 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
16e30 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
16e40 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
16e50 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
16e60 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
16e70 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
16e80 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
16e90 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
16ea0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
16eb0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
16ec0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
16ed0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
16ee0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
16ef0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
16f00 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
16f10 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
16f20 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
16f30 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
16f40 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
16f50 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
16f60 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
16f70 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
16f80 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
16f90 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
16fa0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
16fb0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
16fc0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
16fd0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
16fe0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
16ff0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
17000 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
17010 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
17020 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
17030 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
17040 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
17050 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
17060 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
17070 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
17080 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
17090 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
170a0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
170b0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
170c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
170d0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
170e0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
170f0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
17100 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
17110 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
17120 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
17130 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
17140 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
17150 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
17160 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
17170 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
17180 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
17190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
171a0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
171b0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
171c0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
171d0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
171e0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
171f0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
17200 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
17210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17220 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
17230 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
17240 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
17250 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17260 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
17270 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17280 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
17290 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
172a0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
172b0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
172c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
172d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
172e0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
172f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17300 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
17310 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
17320 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
17330 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
17340 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
17350 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
17360 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
17370 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
17380 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17390 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
173a0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
173b0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
173c0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
173d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
173e0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
173f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17400 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17410 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17420 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
17430 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
17440 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
17450 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17460 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
17470 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
17480 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
17490 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
174a0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
174b0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
174c0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
174d0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
174e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
174f0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
17500 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
17510 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17520 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
17530 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
17540 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
17550 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17560 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17570 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
17580 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17590 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
175a0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
175b0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
175c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
175d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
175e0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
175f0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17600 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17610 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17620 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17630 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17650 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17660 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17670 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17680 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17690 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
176a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
176b0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
176c0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
176d0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
176e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
176f0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17700 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17710 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17720 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
17730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
17740 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
17750 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
17760 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
17770 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
17780 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17790 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
177a0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
177b0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
177c0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
177d0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
177e0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
177f0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17800 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17810 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17830 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
17840 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
17850 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
17860 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
17870 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
17880 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
17890 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
178a0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
178b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
178c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
178d0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
178e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
178f0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
17900 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
17910 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
17920 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
17930 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
17940 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
17950 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
17960 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
17970 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
17980 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
17990 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
179a0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
179b0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
179c0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
179d0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
179e0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
179f0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
17a00 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
17a10 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
17a20 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
17a30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
17a40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17a50 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
17a60 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
17a70 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
17a80 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
17a90 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
17aa0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
17ab0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
17ac0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
17ad0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
17ae0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
17af0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
17b00 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
17b10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
17b20 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
17b30 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
17b40 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
17b50 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
17b60 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
17b70 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
17b80 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
17b90 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
17ba0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
17bb0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
17bc0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
17bd0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
17be0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
17bf0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
17c00 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
17c10 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
17c20 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
17c30 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
17c40 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
17c50 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
17c60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
17c70 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
17c80 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
17c90 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
17ca0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
17cb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
17cc0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
17cd0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
17ce0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
17cf0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
17d00 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
17d10 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
17d20 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
17d30 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
17d40 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
17d50 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
17d60 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
17d70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
17d80 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
17d90 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
17da0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
17db0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
17dc0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
17dd0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
17de0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
17df0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
17e00 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
17e10 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
17e20 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
17e30 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
17e40 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
17e50 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
17e60 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
17e70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
17e80 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
17e90 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17ea0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
17eb0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
17ec0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
17ed0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
17ee0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
17ef0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
17f00 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
17f10 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
17f20 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
17f30 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
17f40 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
17f50 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
17f60 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
17f70 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
17f80 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
17f90 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
17fa0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
17fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
17fc0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
17fd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17fe0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
17ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18000 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
18010 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
18020 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
18030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18040 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
18050 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
18060 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
18070 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
18080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18090 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
180a0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
180b0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
180c0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
180d0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
180e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
180f0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
18100 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
18110 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
18120 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
18130 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
18140 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
18150 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
18160 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
18170 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
18180 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18190 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
181a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
181b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
181c0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
181d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
181e0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
181f0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
18200 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
18210 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
18220 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
18230 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
18240 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
18250 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
18260 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
18270 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
18280 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
18290 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
182a0 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
182b0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
182c0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
182d0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
182e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
182f0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18300 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18310 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18320 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18330 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18340 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18350 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18370 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
18380 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
18390 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
183a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
183b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
183c0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
183d0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
183e0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
183f0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18400 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18410 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
18420 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
18430 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
18440 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
18450 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
18460 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18470 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18480 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
18490 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
184a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
184b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
184c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
184d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
184e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
184f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18500 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18510 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
18520 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
18530 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
18540 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
18550 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
18560 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
18570 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
18580 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18590 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
185a0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
185b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
185c0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
185d0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
185e0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
185f0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18600 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18610 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18620 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18630 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
18640 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
18650 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
18660 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
18670 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
18680 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18690 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
186a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
186b0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
186c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
186d0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
186e0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
186f0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18700 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18710 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18720 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
18730 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
18740 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
18750 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
18760 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18770 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18780 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18790 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
187a0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
187b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
187c0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
187d0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
187e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
187f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18800 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18810 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18820 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
18830 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
18840 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
18850 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18860 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
18870 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
18880 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
18890 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
188a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
188b0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
188c0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
188d0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
188e0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
188f0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
18900 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
18910 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
18920 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
18940 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
18950 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
18960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18970 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
18980 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
18990 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
189a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
189b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
189c0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
189d0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
189e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
189f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18a10 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
18a20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
18a30 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18a40 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18a60 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
18a70 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
18a80 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18a90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18aa0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18ab0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
18ac0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
18ad0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18ae0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18af0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18b00 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
18b10 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
18b20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18b30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18b40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18b50 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
18b60 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18b70 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18b80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
18ba0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
18bb0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18bc0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18bd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18be0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
18bf0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
18c00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18c10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18c20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18c30 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
18c40 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
18c50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18c60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18c70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c80 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
18c90 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
18ca0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18cb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18cd0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
18ce0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
18cf0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18d00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d20 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
18d30 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
18d40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18d50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d70 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
18d80 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
18d90 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18da0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18db0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18dc0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
18dd0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
18de0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18df0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18e10 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
18e20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
18e30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18e40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18e60 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
18e70 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
18e80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18e90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
18eb0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
18ec0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
18ed0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18ee0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
18f00 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
18f10 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
18f20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
18f30 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
18f40 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
18f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f60 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
18f70 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
18f80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
18f90 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
18fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18fb0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
18fc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18fd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18fe0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
18ff0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
19000 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
19010 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19030 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19040 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19050 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19060 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
19070 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19080 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
19090 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
190a0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
190b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
190c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
190d0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
190e0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
190f0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
19100 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19120 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19130 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19140 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19150 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19170 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
19180 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
19190 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
191a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
191b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
191c0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
191d0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
191e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
191f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19210 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
19220 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19230 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19240 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19260 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
19270 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
19280 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
19290 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
192a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
192b0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
192c0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
192d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
192e0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
192f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19300 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
19310 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
19320 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
19330 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
19340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19350 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
19360 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
19370 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
19380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
19390 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
193a0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
193b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
193c0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
193d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
193e0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
193f0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
19400 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
19410 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
19420 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19430 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19440 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19450 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19460 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
19470 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
19480 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
19490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
194a0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
194b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
194c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
194d0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
194e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
194f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19500 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
19510 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19520 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19530 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19540 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
19550 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
19560 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19570 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
19580 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19590 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
195a0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
195b0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
195c0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
195d0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
195e0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
195f0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19600 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19610 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19620 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19630 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19640 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19650 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19660 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
19670 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19680 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19690 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
196a0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
196b0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
196c0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
196d0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
196e0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
196f0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a  took to run..*/.
19700 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
19710 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
19720 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
19730 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
19740 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
19750 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
19760 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
19770 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
19780 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
19790 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
197a0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
197b0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
197c0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
197d0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
197e0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
197f0 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
19800 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
19810 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
19820 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19830 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
19840 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
19850 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
19860 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
19870 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
19880 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
19890 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
198a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
198b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
198c0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
198d0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
198e0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
198f0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
19900 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  query..**.** ^If
19910 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19920 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19930 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
19940 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
19950 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
19960 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
19970 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
19980 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
19990 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
199a0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
199b0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
199c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
199d0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
199e0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
199f0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19a10 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19a20 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19a30 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
19a40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19a50 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
19a60 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
19a70 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
19a80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19a90 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
19aa0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
19ab0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
19ac0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
19ad0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19ae0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19af0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
19b00 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
19b10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19b20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
19b30 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
19b40 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
19b50 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
19b60 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
19b70 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
19b80 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
19b90 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
19ba0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
19bb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
19bc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
19bd0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
19be0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
19bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19c00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
19c10 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19c20 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
19c30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
19c40 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
19c50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
19c60 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
19c70 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
19c80 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
19c90 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
19ca0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
19cb0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
19cc0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
19cd0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
19ce0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
19cf0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
19d00 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
19d10 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
19d20 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
19d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
19d40 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
19d50 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
19d60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19d70 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
19d80 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
19d90 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
19da0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
19db0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
19dc0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
19dd0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
19de0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
19df0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
19e00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
19e10 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
19e20 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
19e30 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
19e40 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
19e50 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
19e60 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
19e70 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
19e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
19e90 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
19ea0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19eb0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
19ec0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
19ed0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
19ee0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
19ef0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19f00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
19f10 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
19f20 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
19f30 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
19f40 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
19f50 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
19f60 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
19f70 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
19f80 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
19f90 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
19fa0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
19fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19fc0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
19fd0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
19fe0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
19ff0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1a000 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1a010 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1a020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a030 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1a040 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1a050 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1a060 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1a070 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1a080 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1a090 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1a0a0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1a0b0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1a0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1a0d0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1a0e0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1a0f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1a100 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1a110 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1a120 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1a130 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1a140 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1a150 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a160 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1a170 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1a180 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1a190 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f  DCACHE],.** and/
1a1a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1a1b0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1a1c0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1a1d0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1a1e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1a1f0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1a200 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a210 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1a220 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1a230 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1a240 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1a250 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1a260 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1a270 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1a280 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a290 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1a2a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a2b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1a2c0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1a2d0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1a2e0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1a2f0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1a300 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1a310 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1a320 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1a330 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1a340 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1a350 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1a360 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1a370 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1a380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1a390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a3a0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1a3b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1a3c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1a3d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1a3e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1a3f0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1a400 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a   creates it if.*
1a410 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1a420 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1a430 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1a440 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1a450 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1a460 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1a470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1a480 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1a490 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1a4a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1a4b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a4c0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1a4d0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1a4e0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1a4f0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
1a500 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1a510 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
1a520 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
1a530 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1a540 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1a550 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
1a560 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1a570 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
1a580 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1a590 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
1a5a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1a5b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1a5c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1a5d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1a5e0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1a5f0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1a600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a610 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1a620 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1a630 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1a640 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1a650 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1a660 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1a670 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1a680 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1a690 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1a6a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1a6b0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1a6c0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1a6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a6e0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1a6f0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1a700 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1a710 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1a720 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1a730 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1a740 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1a750 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1a760 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1a770 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1a780 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1a790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a7a0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1a7b0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1a7c0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1a7d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1a7e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1a7f0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1a800 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1a810 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1a820 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1a830 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1a840 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1a850 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1a860 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a870 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1a880 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1a890 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1a8a0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1a8b0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1a8c0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1a8d0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1a8e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1a8f0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1a900 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1a910 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1a920 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1a930 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1a940 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1a950 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1a960 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a970 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1a980 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1a990 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1a9a0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1a9b0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1a9c0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1a9d0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1a9e0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1a9f0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1aa00 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1aa10 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1aa20 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1aa30 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1aa40 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1aa50 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1aa60 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1aa70 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1aa80 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1aa90 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1aaa0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1aab0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1aac0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1aad0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1aae0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1aaf0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1ab00 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1ab10 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1ab20 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1ab30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1ab40 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1ab50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1ab60 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1ab70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  sed..**.** ^The 
1ab80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1ab90 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1aba0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1abb0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1abc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1abd0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1abe0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1abf0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1ac00 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1ac10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ac20 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1ac30 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1ac40 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1ac50 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1ac60 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1ac70 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ac80 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1ac90 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1aca0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1acb0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1acc0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1acd0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1ace0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1acf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1ad00 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1ad10 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1ad20 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1ad30 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1ad40 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1ad50 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1ad60 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1ad70 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1ad80 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1ad90 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1ada0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1adb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1adc0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1add0 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  2()..*/.int sqli
1ade0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1adf0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ae00 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ae10 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ae20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ae30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1ae40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ae50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1ae60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1ae70 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1ae80 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1ae90 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1aea0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1aeb0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aec0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1aed0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1aee0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1aef0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1af00 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1af10 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1af20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1af30 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1af40 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1af50 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1af60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1af70 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1af80 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1af90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1afa0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1afb0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1afc0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1afd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1afe0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1aff0 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
1b000 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1b010 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1b020 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1b030 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1b040 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1b050 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1b060 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b070 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1b080 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1b090 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1b0a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b0b0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1b0c0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1b0d0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1b0e0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1b0f0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1b100 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1b110 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1b120 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1b130 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
1b140 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1b150 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
1b160 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
1b170 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1b180 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
1b190 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
1b1a0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
1b1b0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
1b1c0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
1b1d0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
1b1e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b1f0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1b200 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1b210 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1b220 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1b230 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1b240 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1b250 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1b260 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1b270 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
1b280 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1b290 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1b2a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1b2b0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1b2c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1b2d0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1b2e0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1b2f0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1b300 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1b310 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1b320 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1b330 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1b340 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1b350 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1b360 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1b370 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
1b380 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1b390 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1b3a0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1b3b0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1b3c0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1b3d0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1b3e0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1b3f0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1b400 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1b410 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1b420 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1b430 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1b440 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1b450 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1b460 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1b470 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1b480 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1b490 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1b4a0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1b4b0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1b4c0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1b4d0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1b4e0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1b4f0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1b500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b510 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1b520 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1b530 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1b540 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1b550 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1b560 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1b570 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1b580 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1b590 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1b5a0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1b5b0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1b5c0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1b5d0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1b5e0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1b5f0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1b600 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1b610 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1b620 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1b630 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1b640 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1b650 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1b660 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1b670 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1b680 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1b690 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1b6a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b6b0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1b6c0 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
1b6d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1b6e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1b6f0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1b700 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1b710 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1b720 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1b730 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1b740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b750 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1b760 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1b770 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1b780 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1b790 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1b7a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1b7b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1b7c0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1b7d0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1b7e0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1b7f0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1b800 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1b810 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1b820 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1b830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1b840 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1b850 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1b860 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1b870 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1b880 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1b890 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b8a0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1b8b0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1b8c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1b8d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1b8e0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1b8f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1b900 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1b910 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1b920 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1b930 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1b940 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1b950 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1b960 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1b970 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1b980 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1b990 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1b9a0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1b9b0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b9c0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1b9d0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1b9e0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1b9f0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1ba00 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1ba10 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1ba20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1ba30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1ba40 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1ba50 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1ba60 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1ba70 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1ba80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1ba90 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1baa0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1bab0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1bac0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1bad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1bae0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
1baf0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
1bb00 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1bb10 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1bb20 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1bb30 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1bb40 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1bb50 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1bb60 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1bb70 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1bb80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bb90 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1bba0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1bbb0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1bbc0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1bbd0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1bbe0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1bbf0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1bc00 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1bc10 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1bc20 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1bc30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1bc40 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1bc50 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1bc60 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1bc70 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1bc80 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e  the old limit.)^
1bc90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
1bca0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
1bcb0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
1bcc0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
1bcd0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
1bce0 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
1bcf0 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
1bd00 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
1bd10 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
1bd20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1bd30 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f  ].** set by a co
1bd40 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1bd50 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1bd60 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74  named .** [limit
1bd70 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  s | SQLITE_MAX_X
1bd80 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  YZ]..** (The "_L
1bd90 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1bda0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1bdb0 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
1bdc0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
1bdd0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1bde0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1bdf0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1be00 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1be10 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1be20 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
1be30 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
1be40 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1be50 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1be60 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1be70 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1be80 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1be90 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1bea0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1beb0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1bec0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1bed0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1bee0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1bef0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1bf00 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
1bf10 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1bf20 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1bf30 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1bf40 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1bf50 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1bf60 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1bf70 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1bf80 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1bf90 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1bfa0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1bfb0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1bfc0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1bfd0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1bfe0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1bff0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1c000 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1c010 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1c020 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1c030 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1c040 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1c050 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1c060 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1c070 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1c080 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1c090 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1c0a0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1c0b0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1c0c0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1c0d0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1c0e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1c0f0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1c100 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1c110 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1c120 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1c130 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1c140 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1c150 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1c160 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1c170 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1c180 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
1c190 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1c1a0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c1b0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1c1c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c1d0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1c1e0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
1c1f0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1c200 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
1c210 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1c220 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1c230 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1c240 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
1c250 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
1c260 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
1c270 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
1c280 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1c290 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
1c2a0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
1c2b0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1c2c0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
1c2d0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
1c2e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1c2f0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
1c300 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
1c310 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
1c320 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1c330 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c340 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1c350 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
1c360 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
1c370 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
1c380 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a  le row.<dd>)^.**
1c390 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c3a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1c3b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1c3c0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1c3d0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1c3e0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
1c3f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c400 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c410 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
1c420 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c430 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1c440 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
1c450 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
1c460 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
1c470 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
1c480 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1c490 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1c4a0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
1c4b0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
1c4c0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
1c4d0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
1c4e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c4f0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1c500 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c510 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1c520 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1c530 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1c540 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c550 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c560 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1c570 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c580 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c590 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1c5a0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1c5b0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
1c5c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c5d0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1c5e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c5f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c600 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
1c610 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
1c620 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
1c630 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1c640 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
1c650 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1c660 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c670 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1c680 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c690 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c6a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1c6b0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1c6c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c6d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1c6e0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1c6f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c700 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1c710 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1c720 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1c730 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1c740 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1c750 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1c760 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c770 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1c780 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1c790 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1c7a0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1c7b0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1c7c0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c7d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1c7e0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1c7f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c800 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1c810 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1c820 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1c830 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1c840 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c850 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1c860 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1c870 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c880 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1c890 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1c8a0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1c8b0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1c8c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1c8d0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c8e0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1c8f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1c900 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c910 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1c920 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c930 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1c940 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1c950 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1c960 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1c970 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1c980 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c990 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1c9a0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1c9b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c9c0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1c9d0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1c9e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c9f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1ca00 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1ca10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1ca20 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1ca30 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1ca40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ca50 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1ca60 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1ca70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ca80 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1ca90 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1caa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cab0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1cac0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1cad0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1cae0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1caf0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1cb00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1cb10 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1cb20 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1cb30 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1cb40 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1cb50 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1cb60 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1cb70 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1cb80 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1cb90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1cba0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1cbb0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1cbc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1cbd0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1cbe0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1cbf0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1cc00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1cc10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1cc20 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1cc30 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1cc40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1cc50 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1cc60 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1cc70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1cc80 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1cc90 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1cca0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1ccb0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1ccc0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1ccd0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1cce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ccf0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1cd00 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1cd10 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1cd20 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1cd30 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1cd40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1cd50 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1cd60 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1cd70 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1cd80 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1cd90 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1cda0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1cdb0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1cdc0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1cdd0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1cde0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1cdf0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1ce00 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1ce10 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1ce20 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1ce30 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1ce40 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1ce50 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1ce60 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1ce70 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1ce80 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1ce90 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1cea0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1ceb0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1cec0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1ced0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1cee0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1cef0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1cf00 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1cf10 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1cf20 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1cf30 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1cf40 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1cf50 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1cf60 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1cf70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1cf80 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1cf90 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1cfa0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1cfb0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1cfc0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1cfd0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1cfe0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1cff0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1d000 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1d010 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1d020 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1d030 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1d040 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1d050 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1d060 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1d070 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1d080 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1d090 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1d0a0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1d0b0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1d0c0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1d0d0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1d0e0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1d0f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1d100 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1d110 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1d120 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1d130 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1d140 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1d150 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1d160 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1d170 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1d180 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1d190 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1d1a0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1d1b0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1d1c0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1d1d0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1d1e0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1d1f0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1d200 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1d210 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1d220 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1d230 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d240 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1d250 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1d260 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1d270 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1d280 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1d290 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d2a0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1d2b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1d2c0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1d2d0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1d2e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1d2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1d300 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1d320 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1d330 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1d340 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1d350 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1d360 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1d370 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1d380 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1d390 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d3a0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1d3b0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1d3c0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1d3d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1d3e0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1d3f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1d400 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1d410 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1d420 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1d430 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1d440 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1d450 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1d460 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1d470 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1d480 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1d490 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1d4a0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1d4b0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1d4c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d4d0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1d4e0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1d4f0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1d500 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1d510 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1d520 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d530 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1d540 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1d550 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1d560 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1d570 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49  un it again.  ^I
1d580 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1d590 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1d5a0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1d5b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1d5c0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1d5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d5e0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1d5f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1d600 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1d610 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1d620 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1d630 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1d640 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1d650 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1d660 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d670 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1d680 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1d690 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1d6a0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1d6b0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1d6c0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1d6d0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1d6e0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1d6f0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1d700 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1d710 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1d720 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1d730 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1d740 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d750 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1d760 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1d770 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1d780 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1d790 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1d7a0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1d7b0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1d7c0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1d7d0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1d7e0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1d7f0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1d800 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
1d810 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
1d820 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1d830 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1d840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
1d850 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1d860 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1d870 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1d880 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1d890 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1d8a0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1d8b0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1d8c0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1d8d0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1d8e0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1d8f0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1d900 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ^If the value of
1d910 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20   a [parameter | 
1d920 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1d930 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  in the WHERE cla
1d940 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61  use might.** cha
1d950 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70 6c  nge the query pl
1d960 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
1d970 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61  nt, then the sta
1d980 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a  tement may be.**
1d990 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1d9a0 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66  ecompiled (as if
1d9b0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
1d9c0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29  a schema change)
1d9d0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a   on the first .*
1d9e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1d9f0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1da00 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20  g any change to 
1da10 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1da20 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
1da30 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70  dings] of the [p
1da40 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c  arameter]. .** <
1da50 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
1da60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1da70 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1da80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1da90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1daa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1dab0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1dac0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1dad0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1dae0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1daf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1db00 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1db10 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1db20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1db30 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1db40 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1db50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1db60 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1db70 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1db80 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1db90 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1dba0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1dbb0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1dbc0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1dbd0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1dbe0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1dbf0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1dc00 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1dc10 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1dc20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1dc30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1dc40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1dc50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1dc60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1dc70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1dc80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1dc90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1dca0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1dcb0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1dcc0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1dcd0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1dce0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1dcf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1dd00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1dd10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1dd20 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1dd30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1dd40 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1dd50 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1dd60 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1dd70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1dd80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1dd90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1dda0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1ddb0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1ddc0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1ddd0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1dde0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1ddf0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1de00 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1de10 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1de20 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1de30 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1de40 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1de50 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1de60 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1de70 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1de80 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1de90 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1dea0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1deb0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1dec0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1ded0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1dee0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1def0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1df00 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1df10 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1df20 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1df30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1df40 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1df50 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1df60 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1df70 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1df80 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
1df90 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
1dfa0 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
1dfb0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1dfc0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1dfd0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1dfe0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1dff0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1e000 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1e010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e020 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
1e030 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
1e040 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1e050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e060 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1e070 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e080 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
1e090 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1e0a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1e0b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e0c0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1e0d0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1e0e0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1e0f0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1e100 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1e110 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e120 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1e130 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1e140 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e150 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1e160 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1e170 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1e180 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1e190 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1e1a0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1e1b0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1e1c0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
1e1d0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1e1e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e1f0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1e200 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1e210 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1e220 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1e230 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1e240 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1e250 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1e260 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1e270 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1e280 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1e290 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1e2a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1e2b0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1e2c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1e2d0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1e2e0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1e2f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1e300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1e310 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1e320 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1e330 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1e340 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1e350 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1e360 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1e370 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1e380 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1e390 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1e3a0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1e3b0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1e3c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1e3d0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1e3e0 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1e3f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1e400 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1e410 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e420 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1e430 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1e440 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1e450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e460 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1e470 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1e480 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1e490 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1e4a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1e4b0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1e4c0 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1e4d0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1e4e0 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1e4f0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1e500 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1e510 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1e520 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1e530 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1e540 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1e550 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1e560 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1e570 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1e580 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e590 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1e5a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e5b0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1e5c0 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1e5d0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1e5e0 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1e5f0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1e600 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1e610 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1e620 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1e630 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1e640 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1e650 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1e660 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1e670 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e680 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1e690 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1e6a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
1e6b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e6c0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1e6d0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1e6e0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1e6f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1e700 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1e710 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1e720 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
1e730 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
1e740 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e750 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
1e760 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1e770 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
1e780 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
1e790 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e7a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e7b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
1e7c0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
1e7d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
1e7e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
1e7f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
1e800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
1e810 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
1e820 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
1e830 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
1e840 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1e850 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1e860 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e870 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1e880 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
1e890 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
1e8a0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
1e8b0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1e8c0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
1e8d0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1e8e0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1e8f0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1e900 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1e910 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1e920 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
1e930 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1e940 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
1e950 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1e960 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
1e970 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1e980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1e990 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1e9a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1e9b0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
1e9c0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
1e9d0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
1e9e0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
1e9f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ea00 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1ea10 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1ea20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1ea30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1ea40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
1ea50 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1ea60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1ea70 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
1ea80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1ea90 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
1eaa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1eab0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1eac0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1ead0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1eae0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1eaf0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
1eb00 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1eb10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1eb20 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1eb30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1eb40 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1eb50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1eb60 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1eb70 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1eb80 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1eb90 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1eba0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1ebb0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
1ebc0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
1ebd0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1ebe0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1ebf0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
1ec00 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1ec10 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
1ec20 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
1ec30 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
1ec40 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
1ec50 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
1ec60 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1ec70 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1ec80 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1ec90 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1eca0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1ecb0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
1ecc0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
1ecd0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
1ece0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1ecf0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
1ed00 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
1ed10 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29  eric identifer.)
1ed20 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
1ed30 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
1ed40 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
1ed50 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
1ed60 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
1ed70 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1ed80 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1ed90 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1eda0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1edb0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1edc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1edd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1ede0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1edf0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
1ee00 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
1ee10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ee20 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
1ee30 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
1ee40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ee50 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1ee60 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
1ee70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1ee80 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1ee90 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
1eea0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
1eeb0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
1eec0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
1eed0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
1eee0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
1eef0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
1ef00 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
1ef10 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
1ef20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
1ef30 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
1ef40 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
1ef50 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
1ef60 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1ef70 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
1ef80 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1ef90 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1efa0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1efb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1efc0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1efd0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1efe0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
1eff0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1f000 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1f010 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1f020 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
1f030 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1f040 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
1f050 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
1f060 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
1f070 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1f080 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
1f090 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
1f0a0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
1f0b0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
1f0c0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
1f0d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f0e0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
1f0f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
1f100 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
1f110 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
1f120 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1f130 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1f140 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
1f150 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
1f160 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1f170 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1f180 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
1f190 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
1f1a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
1f1b0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
1f1c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1f1d0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
1f1e0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
1f1f0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
1f200 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1f210 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1f220 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1f230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
1f240 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1f250 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1f260 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1f270 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1f280 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f290 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1f2a0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1f2b0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1f2c0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1f2d0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1f2e0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1f2f0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
1f300 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1f310 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1f320 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1f330 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1f340 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1f350 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1f360 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1f370 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1f380 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1f390 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
1f3a0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1f3b0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1f3c0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1f3d0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
1f3e0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
1f3f0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1f400 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
1f410 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
1f420 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
1f430 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
1f440 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
1f450 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f460 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1f470 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1f480 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1f490 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1f4a0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
1f4b0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
1f4c0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
1f4d0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
1f4e0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
1f4f0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
1f500 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
1f510 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
1f520 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
1f530 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
1f540 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1f550 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
1f560 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
1f570 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
1f580 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1f590 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
1f5a0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
1f5b0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
1f5c0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
1f5d0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1f5e0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1f5f0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1f600 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
1f610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1f620 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1f630 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1f640 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
1f650 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f660 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
1f670 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
1f680 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
1f690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1f6a0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
1f6b0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
1f6c0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
1f6d0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
1f6e0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
1f6f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
1f700 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
1f710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
1f720 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
1f730 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
1f740 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1f750 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
1f760 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
1f770 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
1f780 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
1f790 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
1f7a0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
1f7b0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
1f7c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
1f7d0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
1f7e0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
1f7f0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
1f800 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
1f810 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f820 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
1f830 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
1f840 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
1f850 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
1f860 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
1f870 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
1f880 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1f890 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1f8a0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1f8b0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1f8c0 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
1f8d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1f8e0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1f8f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1f900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f910 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1f920 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f930 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f940 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
1f950 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f960 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
1f970 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f980 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
1f990 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1f9a0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
1f9b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1f9c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f9d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
1f9e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
1f9f0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
1fa00 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
1fa10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1fa20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1fa30 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
1fa40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
1fa50 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
1fa60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
1fa70 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
1fa80 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
1fa90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
1faa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1fab0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
1fac0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
1fad0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1fae0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1faf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1fb00 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1fb10 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1fb20 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1fb30 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
1fb40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1fb50 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
1fb60 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
1fb70 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1fb80 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1fb90 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
1fba0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fbb0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
1fbc0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
1fbd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
1fbe0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
1fbf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
1fc00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
1fc10 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
1fc20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
1fc30 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1fc40 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1fc50 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1fc60 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1fc70 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1fc80 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1fc90 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1fca0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
1fcb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1fcc0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
1fcd0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1fce0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
1fcf0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
1fd00 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
1fd10 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
1fd20 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
1fd30 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
1fd40 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
1fd50 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
1fd60 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
1fd70 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
1fd80 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1fd90 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
1fda0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
1fdb0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
1fdc0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
1fdd0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
1fde0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
1fdf0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1fe00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1fe10 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1fe20 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1fe30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fe40 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
1fe50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1fe60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1fe70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1fe80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fe90 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
1fea0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1feb0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
1fec0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
1fed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1fee0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1fef0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
1ff00 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1ff10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ff20 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
1ff30 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
1ff40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ff50 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
1ff60 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1ff70 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
1ff80 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1ff90 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
1ffa0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
1ffb0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
1ffc0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1ffd0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1ffe0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
1fff0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
20000 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
20010 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
20020 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
20030 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
20040 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
20050 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
20060 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
20070 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
20080 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
20090 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
200a0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
200b0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
200c0 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
200d0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
200e0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
200f0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
20100 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
20110 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
20120 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
20130 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
20140 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
20150 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
20160 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
20170 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
20180 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
20190 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
201a0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
201b0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
201c0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
201d0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
201e0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
201f0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
20200 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
20210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20220 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
20230 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20240 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20250 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20270 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20280 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20290 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
202a0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
202b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
202c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
202d0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
202e0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
202f0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
20300 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
20310 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
20320 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
20330 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
20340 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
20350 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
20360 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
20370 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
20380 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
20390 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
203a0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
203b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
203c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
203d0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
203e0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
203f0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
20400 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
20410 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
20420 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
20430 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
20440 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
20450 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
20460 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
20470 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
20480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20490 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
204a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
204b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
204c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
204d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
204e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
204f0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
20500 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20510 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
20520 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20530 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
20540 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
20550 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
20560 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
20570 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
20580 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
20590 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
205a0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
205b0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
205c0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
205d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
205e0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
205f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
20600 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
20610 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
20620 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
20630 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
20640 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
20650 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
20660 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
20670 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
20680 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
20690 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
206a0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
206b0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
206c0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
206d0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
206e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
206f0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20700 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
20710 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20720 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
20730 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
20740 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
20750 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
20760 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
20770 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
20780 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
20790 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  TE])..*/.int sql
207a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
207b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
207c0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
207d0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
207e0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
207f0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
20800 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
20810 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
20820 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
20830 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
20840 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
20850 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
20860 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
20870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20880 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
20890 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
208a0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
208b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
208c0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
208d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
208e0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
208f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20900 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
20910 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
20920 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
20930 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
20940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20950 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
20960 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
20970 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
20980 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20990 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
209a0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
209b0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
209c0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
209d0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
209e0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
209f0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
20a00 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
20a10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
20a20 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
20a30 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
20a40 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
20a50 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
20a60 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
20a70 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
20a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20a90 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
20aa0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
20ab0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
20ac0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
20ad0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
20ae0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
20af0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
20b00 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
20b10 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
20b20 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
20b30 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
20b40 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
20b50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
20b60 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
20b70 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
20b80 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
20b90 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
20ba0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
20bb0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
20bc0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
20bd0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
20be0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
20bf0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
20c00 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
20c10 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
20c20 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
20c30 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
20c40 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
20c50 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
20c60 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
20c70 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
20c80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
20c90 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20ca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20cb0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
20cc0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
20cd0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
20ce0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
20cf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
20d00 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
20d10 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
20d20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
20d30 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
20d40 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
20d50 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
20d60 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
20d70 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
20d80 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
20d90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
20da0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
20db0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
20dc0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
20dd0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
20de0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
20df0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
20e00 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
20e10 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
20e20 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
20e30 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
20e40 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
20e50 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
20e60 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
20e70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
20e80 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
20e90 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
20ea0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
20eb0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
20ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
20ed0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
20ee0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
20ef0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
20f00 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
20f10 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
20f20 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
20f30 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
20f40 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
20f50 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
20f60 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
20f70 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
20f80 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
20f90 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
20fa0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
20fb0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20fc0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
20fd0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
20fe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20ff0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
21000 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
21010 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
21020 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
21030 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
21040 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
21050 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
21060 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
21070 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
21080 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
21090 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
210a0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
210b0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
210c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
210d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
210e0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
210f0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
21100 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
21110 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
21120 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
21130 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
21140 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
21150 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
21160 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
21170 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
21180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
21190 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
211a0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
211b0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
211c0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
211d0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
211e0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
211f0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
21200 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
21210 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
21220 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
21230 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
21240 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
21250 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
21260 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
21270 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
21280 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
21290 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
212a0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
212b0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
212c0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
212d0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
212e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
212f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
21300 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
21310 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
21320 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
21330 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
21340 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
21350 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
21360 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
21370 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
21380 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21390 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
213a0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
213b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
213c0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
213d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
213e0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
213f0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
21400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
21410 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
21420 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
21430 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
21440 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
21450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21460 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
21470 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
21480 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
21490 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
214a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
214b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
214c0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
214d0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
214e0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
214f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21500 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
21510 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
21520 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
21530 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
21540 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
21550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21560 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
21570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
21580 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
21590 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
215a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
215b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
215c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
215d0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
215e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
215f0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
21600 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21610 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21620 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
21630 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
21640 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
21650 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
21660 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
21670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21680 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
21690 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
216a0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
216b0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
216c0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
216d0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
216e0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
216f0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
21700 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
21710 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
21720 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
21730 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
21740 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
21750 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
21760 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
21770 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
21780 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
21790 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
217a0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
217b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
217c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
217d0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
217e0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
217f0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
21800 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
21810 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
21820 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
21830 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
21840 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
21850 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
21860 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
21870 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
21880 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
21890 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
218a0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
218b0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
218c0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
218d0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
218e0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
218f0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
21900 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
21910 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
21920 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
21930 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
21940 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
21950 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
21960 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
21970 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
21980 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
21990 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
219a0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
219b0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
219c0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
219d0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
219e0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
219f0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
21a00 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
21a10 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
21a20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
21a30 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
21a40 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
21a50 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
21a60 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
21a70 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
21a80 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
21a90 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
21aa0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
21ab0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21ac0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
21ad0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
21ae0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
21af0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
21b00 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
21b10 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
21b20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
21b30 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
21b40 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
21b50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21b60 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
21b70 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
21b80 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
21b90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21ba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
21bb0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
21bc0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
21bd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
21be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21bf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21c00 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
21c10 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
21c20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
21c30 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
21c40 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
21c50 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
21c60 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
21c70 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
21c80 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
21c90 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
21ca0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
21cb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
21cc0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
21cd0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
21ce0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
21cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21d00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21d10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21d20 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
21d30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
21d40 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
21d50 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
21d60 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21d70 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
21d80 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
21d90 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
21da0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
21db0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
21dc0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
21dd0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
21de0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
21df0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
21e00 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
21e10 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
21e20 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
21e30 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
21e40 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
21e50 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
21e60 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
21e70 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
21e80 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
21e90 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
21ea0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
21eb0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
21ec0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
21ed0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21ee0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
21ef0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
21f00 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
21f10 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
21f20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
21f30 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
21f40 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
21f50 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
21f60 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
21f70 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
21f80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
21f90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
21fa0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
21fb0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
21fc0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
21fd0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
21fe0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
21ff0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
22000 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
22010 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
22020 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
22030 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
22040 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
22050 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
22060 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
22070 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
22080 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
22090 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
220a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
220b0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
220c0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
220d0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
220e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
220f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
22100 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
22110 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
22120 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
22130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22140 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
22150 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
22160 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
22170 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
22180 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
22190 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
221a0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
221b0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
221c0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
221d0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
221e0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
221f0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
22200 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
22210 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
22220 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
22230 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
22240 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
22250 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
22260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
22270 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
22280 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
22290 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
222a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
222b0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
222c0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
222d0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
222e0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
222f0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
22300 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
22310 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
22320 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
22330 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
22340 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
22350 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
22360 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
22370 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
22380 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
22390 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
223a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
223b0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
223c0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
223d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
223e0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
223f0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
22400 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
22410 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
22420 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
22430 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22440 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
22450 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
22460 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
22470 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
22480 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
22490 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
224a0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
224b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
224c0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
224d0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
224e0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
224f0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
22500 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
22510 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
22520 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
22530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22540 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
22550 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
22560 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
22570 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
22580 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
22590 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
225a0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
225b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
225c0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
225d0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
225e0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
225f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22600 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
22610 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
22620 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
22630 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
22640 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
22650 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
22660 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
22670 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
22680 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71 75  3.1, it was requ
22690 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71  ired.** after sq
226a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
226b0 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f  urned anything o
226c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
226d0 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b  E_ROW] that.** [
226e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
226f0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
22700 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
22710 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
22720 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
22730 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e  .  Failure to in
22740 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  voke [sqlite3_re
22750 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77  set()] in this w
22760 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75  ay would.** resu
22770 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
22780 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
22790 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65  from sqlite3_ste
227a0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a  p().  But after.
227b0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  ** version 3.6.2
227c0 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
227d0 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e  p() began callin
227e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
227f0 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  ()] .** automati
22800 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
22810 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
22820 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  r than returning
22830 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
22840 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  .  .**.** <b>Goo
22850 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
22860 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
22870 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22880 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
22890 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
228a0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
228b0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
228c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
228d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
228e0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
228f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
22900 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
22910 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
22920 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
22930 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
22940 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22950 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
22960 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
22970 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
22980 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
22990 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
229a0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
229b0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
229c0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
229d0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
229e0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
229f0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
22a00 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
22a10 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
22a20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
22a30 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
22a40 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
22a50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
22a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22a70 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
22a80 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
22a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22aa0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
22ab0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
22ac0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
22ad0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
22ae0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
22af0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
22b00 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
22b10 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
22b20 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
22b30 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
22b40 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
22b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
22b60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
22b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22b80 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
22b90 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
22ba0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
22bb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
22bc0 74 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20  t(P) the number 
22bd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
22be0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
22bf0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
22c00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
22c10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22c20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
22c30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22c50 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
22c60 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
22c70 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
22c80 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
22c90 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
22ca0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
22cb0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
22cc0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
22cd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
22ce0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
22cf0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
22d00 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
22d10 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
22d20 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
22d30 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
22d40 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
22d50 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
22d60 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
22d70 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
22d80 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
22d90 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
22da0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
22db0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
22dc0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22dd0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
22de0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
22df0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
22e00 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
22e10 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
22e20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
22e30 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
22e40 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
22e50 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
22e60 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
22e70 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
22e80 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
22e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
22ea0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
22eb0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
22ec0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
22ed0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
22ee0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
22ef0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
22f00 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
22f10 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
22f20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
22f30 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
22f40 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
22f50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
22f60 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
22f70 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
22f80 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
22f90 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
22fa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
22fb0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
22fc0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
22fd0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
22fe0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
22ff0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
23000 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
23010 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
23020 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
23030 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
23040 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
23050 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23060 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
23070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23080 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
23090 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
230a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
230b0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
230c0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
230d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
230e0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
230f0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
23100 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
23110 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
23120 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
23130 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
23140 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
23150 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
23160 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
23170 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
23180 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
23190 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
231a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
231b0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
231c0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
231d0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
231e0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
231f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
23200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
23210 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
23220 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
23230 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
23240 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
23250 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
23260 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
23270 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
23280 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
23290 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
232a0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
232b0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
232c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
232d0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
232e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
232f0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
23300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
23310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23320 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
23330 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
23340 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
23350 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23360 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
23370 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23380 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23390 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
233a0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
233b0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
233c0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
233d0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
233e0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
233f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
23400 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
23410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
23420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23430 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
23440 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
23450 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
23460 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
23470 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
23480 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
23490 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
234a0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
234b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
234c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
234d0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
234e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
234f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
23500 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
23510 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
23520 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
23530 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
23540 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
23550 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
23560 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
23570 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
23580 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
23590 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
235a0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
235b0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
235c0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
235d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
235e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
235f0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
23600 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
23610 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
23620 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
23630 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
23640 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
23650 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
23660 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
23670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23680 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
23690 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
236a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
236b0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
236c0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
236d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
236e0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
236f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
23700 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23710 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
23720 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
23730 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
23740 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23750 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
23760 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23770 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
23780 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
23790 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
237a0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
237b0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
237c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
237d0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
237e0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
237f0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
23800 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
23810 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
23820 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
23830 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
23840 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
23850 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
23860 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
23870 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
23880 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
23890 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
238a0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
238b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
238c0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
238d0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
238e0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
238f0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
23900 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
23910 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
23920 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
23930 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
23940 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
23950 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
23960 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
23970 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
23980 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23990 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
239a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
239b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
239c0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
239d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
239e0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
239f0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
23a00 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
23a10 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
23a20 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
23a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23a40 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
23a50 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
23a60 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
23a70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
23a80 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
23a90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
23aa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23ab0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
23ac0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
23ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23ae0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
23af0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
23b00 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
23b10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
23b20 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
23b30 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65  .** ^The zero te
23b40 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
23b50 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
23b60 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54   count..**.** ^T
23b70 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
23b80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
23b90 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
23ba0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
23bb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23bc0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
23bd0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
23be0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23bf0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
23c00 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
23c10 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
23c20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
23c30 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
23c40 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
23c50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23c60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
23c70 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
23c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
23c90 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
23ca0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
23cb0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
23cc0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
23cd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
23ce0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
23cf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
23d00 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
23d10 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
23d20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
23d30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
23d40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
23d50 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
23d60 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
23d70 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
23d80 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
23d90 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
23da0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
23db0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
23dc0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
23dd0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
23de0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
23df0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
23e00 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
23e10 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
23e20 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
23e30 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
23e40 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
23e50 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
23e60 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
23e70 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
23e80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
23e90 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
23ea0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
23eb0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
23ec0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
23ed0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
23ee0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
23ef0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
23f00 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23f10 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
23f20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
23f30 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
23f40 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
23f50 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
23f60 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
23f70 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
23f80 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
23f90 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
23fa0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
23fb0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23fc0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
23fd0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
23fe0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
23ff0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
24000 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
24010 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
24020 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
24030 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
24040 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
24050 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
24060 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
24070 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
24080 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
24090 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
240a0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
240b0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
240c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
240d0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
240e0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
240f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
24100 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
24110 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
24120 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
24130 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
24140 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
24150 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
24160 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
24170 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
24180 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
24190 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
241a0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
241b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
241c0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
241d0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
241e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
241f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
24200 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
24210 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
24220 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
24230 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
24240 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
24250 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24260 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
24270 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
24280 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
24290 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
242a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
242b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
242c0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
242d0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
242e0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
242f0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
24300 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
24310 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
24320 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
24330 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
24340 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
24350 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
24360 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
24370 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
24380 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
24390 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
243a0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
243b0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
243c0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
243d0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
243e0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
243f0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
24400 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
24410 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
24420 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
24430 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  ammers..**.** ^N
24440 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
24450 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
24460 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
24470 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
24480 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
24490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
244a0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
244b0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
244c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
244d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
244e0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
244f0 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65  .** ^(Type conve
24500 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
24510 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
24520 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
24530 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
24540 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
24550 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
24560 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24570 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
24580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24590 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
245a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
245b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
245c0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
245d0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
245e0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
245f0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
24600 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
24610 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
24620 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
24630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
24640 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
24650 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
24660 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24670 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
24680 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
24690 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
246a0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
246b0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
246c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
246d0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
246e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
246f0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
24700 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
24710 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
24720 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
24730 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
24740 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
24750 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
24760 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ul>)^.**.** ^Con
24770 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
24780 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
24790 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
247a0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
247b0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
247c0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
247d0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
247e0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
247f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
24800 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
24810 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
24820 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
24830 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
24840 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
24850 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
24860 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
24870 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
24880 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
24890 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
248a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
248b0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
248c0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
248d0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
248e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66  .**.** ^(The saf
248f0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
24900 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
24910 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
24920 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
24930 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
24940 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
24950 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
24960 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
24970 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
24980 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
24990 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
249a0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
249b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
249c0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
249d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
249e0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
249f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24a00 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
24a10 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24a20 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
24a30 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
24a40 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
24a50 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
24a60 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
24a70 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
24a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24a90 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
24aa0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
24ab0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
24ac0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
24ad0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
24ae0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
24af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24b00 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
24b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24b20 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
24b30 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
24b40 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
24b50 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
24b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24b70 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
24b80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
24b90 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
24ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24bb0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
24bc0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
24bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24be0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
24bf0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
24c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
24c20 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
24c30 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
24c40 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
24c50 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
24c60 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
24c70 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
24c80 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
24c90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
24ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
24cb0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
24cc0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
24cd0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
24ce0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
24cf0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
24d00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
24d10 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
24d20 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
24d30 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
24d40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
24d50 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
24d60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
24d70 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
24d80 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
24d90 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
24da0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
24db0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
24dc0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
24dd0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
24de0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
24df0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
24e00 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
24e10 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
24e20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
24e30 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
24e40 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
24e50 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
24e60 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
24e70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
24e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
24e90 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
24ea0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
24eb0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
24ec0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
24ed0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
24ee0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24ef0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24f00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
24f10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24f20 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
24f30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24f40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
24f50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
24f60 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
24f70 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
24f80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24f90 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24fa0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
24fb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24fc0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
24fd0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
24fe0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
24ff0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25000 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
25010 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25020 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
25030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25040 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
25050 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25060 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
25070 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
25090 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
250a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
250b0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
250c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
250d0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
250e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
250f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25100 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
25110 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
25120 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
25130 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25140 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
25150 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
25160 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25170 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
25180 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
25190 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  s executed succe
251a0 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65  ssfully or not e
251b0 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
251c0 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  then.** SQLITE_O
251d0 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e  K is returned. ^
251e0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
251f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
25200 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
25210 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
25220 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
25230 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
25250 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
25260 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
25270 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
25280 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
25290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
252a0 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20  ment].  ^If the 
252b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
252c0 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
252d0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
252e0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
252f0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
25300 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
25310 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
25320 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
25330 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
25340 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63  errupt]..** ^Inc
25350 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
25360 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
25370 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
25380 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
25390 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
253a0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
253b0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
253c0 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
253d0 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
253e0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74  E_ABORT]..*/.int
253f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25400 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
25410 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25420 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
25430 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25440 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
25450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
25460 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
25470 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
25480 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25490 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
254a0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
254b0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
254c0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
254d0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
254e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
254f0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
25500 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
25510 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
25520 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25530 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
25540 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
25550 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
25560 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
25570 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25580 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
25590 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
255a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
255b0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
255c0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
255d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
255e0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
255f0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
25600 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
25610 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
25620 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
25630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25640 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
25650 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25660 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
25670 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
25680 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
25690 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
256a0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
256b0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
256c0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
256d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
256e0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
256f0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
25700 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25710 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
25720 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
25730 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
25740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25750 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
25760 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
25770 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
25780 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
25790 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
257a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
257b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
257c0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
257d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
257e0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
257f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25800 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
25810 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25820 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
25830 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
25840 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25850 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25860 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
25870 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
25880 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
25890 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
258a0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
258b0 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
258c0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
258d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
258e0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
258f0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
25900 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25910 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
25920 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
25930 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
25940 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
25950 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
25960 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
25970 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
25980 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
25990 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
259a0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
259b0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
259c0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
259d0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
259e0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
259f0 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
25a00 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
25a10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
25a20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25a30 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
25a40 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
25a50 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
25a60 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
25a70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25a80 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
25a90 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
25aa0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25ab0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  6()..**.** ^The 
25ac0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25ad0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
25ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
25af0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
25b00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
25b10 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
25b20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
25b30 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
25b40 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
25b50 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
25b60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25b70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
25b80 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
25b90 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
25ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
25bb0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
25bc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
25bd0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
25be0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
25bf0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
25c00 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
25c10 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
25c20 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
25c30 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
25c40 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
25c50 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
25c60 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
25c70 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
25c80 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
25c90 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
25ca0 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20  aracters.  ^Any 
25cb0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
25cc0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
25cd0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
25ce0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
25cf0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
25d00 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
25d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
25d20 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
25d30 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
25d40 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
25d50 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
25d60 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
25d70 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
25d80 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
25d90 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
25da0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
25db0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
25dc0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
25dd0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
25de0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
25df0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
25e00 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
25e10 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
25e20 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
25e30 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
25e40 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
25e50 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
25e60 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
25e70 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25e80 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
25e90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
25ea0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
25eb0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
25ec0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
25ed0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
25ee0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
25ef0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
25f00 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
25f10 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
25f20 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
25f30 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
25f40 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
25f50 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
25f60 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
25f70 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
25f80 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
25f90 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
25fa0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
25fb0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
25fc0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
25fd0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
25fe0 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
25ff0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26000 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
26010 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26020 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
26030 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
26040 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
26050 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
26060 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
26070 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
26080 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
26090 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
260a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
260b0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
260c0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
260d0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
260e0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
260f0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
26100 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
26110 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
26120 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
26130 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
26140 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
26150 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
26160 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
26170 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
26180 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
26190 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
261a0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
261b0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
261c0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
261d0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
261e0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
261f0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
26200 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
26210 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
26220 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
26230 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].)^.**.** The 
26240 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
26250 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
26260 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
26270 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
26280 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
26290 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
262a0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
262b0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
262c0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
262d0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
262e0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
262f0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
26300 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
26310 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
26320 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
26330 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
26340 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
26350 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
26360 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
26370 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
26380 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
26390 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
263a0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
263b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
263c0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
263d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
263e0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
263f0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
26400 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
26410 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
26420 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
26430 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
26440 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
26450 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
26460 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
26470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
26480 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
26490 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
264a0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
264b0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
264c0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
264d0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
264e0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
264f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
26500 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
26510 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
26520 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
26530 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
26540 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
26550 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
26560 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
26570 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
26580 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26590 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
265a0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
265b0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
265c0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
265d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
265e0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
265f0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
26600 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
26610 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
26620 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
26630 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
26640 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
26650 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
26660 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26670 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26680 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
26690 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
266a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
266b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
266c0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
266d0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
266e0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
266f0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
26700 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
26710 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
26720 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
26730 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
26740 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
26750 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
26760 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
26770 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
26780 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26790 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ions..** ^The fi
267a0 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
267b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
267c0 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
267d0 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
267e0 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
267f0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
26800 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
26810 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
26820 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
26830 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c  ^Subsequent appl
26840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26850 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
26860 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
26870 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
26880 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
26890 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
268a0 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
268b0 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
268c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
268d0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
268e0 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
268f0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
26900 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26910 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
26920 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
26930 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
26940 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
26950 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
26960 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
26970 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26980 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
26990 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
269a0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
269b0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
269c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
269d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
269e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
269f0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
26a00 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
26a10 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
26a20 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
26a30 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
26a40 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
26a50 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
26a60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26a70 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
26a80 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
26a90 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
26aa0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26ab0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26ac0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
26ad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
26ae0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
26af0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26b00 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
26b10 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
26b20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
26b30 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
26b40 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
26b50 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
26b60 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
26b70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
26b80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
26b90 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
26ba0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26bb0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
26bc0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
26bd0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
26be0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
26bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
26c00 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
26c10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26c20 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
26c30 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
26c40 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
26c50 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
26c60 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
26c70 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
26c80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
26c90 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
26ca0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26cb0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
26cc0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26cd0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
26ce0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26cf0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
26d00 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
26d10 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
26d20 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
26d30 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
26d40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
26d50 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
26d60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26d70 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
26d80 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
26d90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
26da0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
26db0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
26dc0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
26dd0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
26de0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
26df0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
26e00 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
26e10 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
26e20 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
26e30 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
26e40 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
26e50 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
26e60 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
26e70 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
26e80 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
26e90 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
26ea0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
26eb0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
26ec0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
26ed0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
26ee0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
26ef0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
26f00 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
26f10 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
26f20 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
26f30 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
26f40 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
26f50 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
26f60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
26f70 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
26f80 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
26f90 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
26fa0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
26fb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
26fc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
26fd0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
26fe0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
26ff0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
27000 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
27010 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
27020 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
27030 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
27040 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
27050 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
27060 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
27070 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
27080 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
27090 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
270a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
270b0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
270c0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
270d0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
270e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
270f0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
27100 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
27110 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
27120 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
27130 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
27140 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
27150 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
27160 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
27170 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
27180 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
27190 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
271a0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
271b0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
271c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
271d0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
271e0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
271f0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
27200 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
27210 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
27220 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
27230 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27240 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27250 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
27260 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
27270 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
27280 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27290 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
272a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
272b0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
272c0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
272d0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
272e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
272f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
27300 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
27310 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27320 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
27330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
27340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
27350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
27360 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
27370 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
27380 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
27390 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
273a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
273b0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
273c0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
273d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
273e0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
273f0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
27400 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
27410 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27420 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
27430 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
27440 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
27450 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
27460 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
27470 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
27480 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
27490 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
274a0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
274b0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
274c0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
274d0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
274e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
274f0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
27500 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
27510 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
27520 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
27530 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
27540 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
27550 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27560 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
27570 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
27580 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
27590 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
275a0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
275b0 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
275c0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
275d0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
275e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
275f0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
27600 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
27610 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
27620 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
27630 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
27640 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
27650 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
27660 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27670 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
27680 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
27690 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
276a0 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
276b0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
276c0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
276d0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
276e0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
276f0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
27700 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
27710 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
27720 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
27730 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
27740 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
27750 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
27760 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
27770 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
27780 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27790 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
277a0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
277b0 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
277c0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
277d0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
277e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
277f0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
27800 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
27810 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
27820 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
27830 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
27840 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
27850 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
27860 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
27870 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
27880 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
27890 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
278a0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
278b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
278c0 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
278d0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
278e0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
278f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27900 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
27910 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
27920 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
27930 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
27940 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
27950 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
27960 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
27970 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
27980 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
27990 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
279a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
279b0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
279c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
279d0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
279e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
279f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
27a00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
27a10 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
27a20 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
27a30 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27a40 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
27a50 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
27a60 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
27a70 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
27a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27aa0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
27ab0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
27ac0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
27ad0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
27ae0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
27af0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
27b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27b10 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
27b20 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
27b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27b40 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
27b50 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
27b60 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27b70 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
27b80 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
27b90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
27ba0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
27bb0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27bd0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
27be0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
27bf0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
27c00 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
27c10 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
27c20 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
27c30 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
27c40 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
27c50 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61  plementions of a
27c60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
27c70 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
27c80 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
27c90 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
27ca0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
27cb0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
27cc0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
27cd0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27ce0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
27cf0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
27d00 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
27d10 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
27d20 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
27d30 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
27d40 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
27d50 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
27d60 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
27d70 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
27d80 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
27d90 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
27da0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27db0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
27dc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27dd0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
27de0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
27df0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
27e00 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
27e10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
27e20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27e30 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
27e40 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
27e50 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
27e60 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
27e70 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
27e80 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
27e90 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
27ea0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
27eb0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
27ec0 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
27ed0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
27ee0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
27ef0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
27f00 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
27f10 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
27f20 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
27f30 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
27f40 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
27f50 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
27f60 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
27f70 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
27f80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
27f90 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
27fa0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
27fb0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
27fc0 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
27fd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27fe0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27ff0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
28000 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
28010 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
28020 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
28030 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
28040 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28050 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
28060 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
28070 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
28080 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
28090 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
280a0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
280b0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
280c0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
280d0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
280e0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
280f0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
28100 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
28110 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
28120 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28130 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
28140 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
28150 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
28160 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
28170 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
28180 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
28190 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
281a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
281b0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
281c0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
281d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
281e0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
281f0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
28200 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
28210 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
28220 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
28230 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
28240 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
28250 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
28260 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
28270 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
28280 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
28290 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
282a0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
282b0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
282c0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
282d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
282e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
282f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
28300 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
28310 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
28320 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
28330 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
28340 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
28350 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28360 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
28370 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
28380 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
28390 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
283a0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
283b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
283c0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
283d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
283e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
283f0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
28400 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
28410 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
28420 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
28430 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
28440 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28450 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
28460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28470 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
28480 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
28490 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
284a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
284b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
284c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
284d0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
284e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
284f0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
28500 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
28510 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28520 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
28530 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
28540 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
28550 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28570 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
28580 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
28590 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
285a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
285b0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
285c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
285d0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
285e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
285f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28600 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
28610 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
28620 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
28630 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
28640 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
28650 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
28660 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
28670 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
28680 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
28690 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
286a0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
286b0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
286c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
286d0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
286e0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
286f0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
28700 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
28710 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28720 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
28730 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
28740 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
28750 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
28760 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
28770 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
28780 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
28790 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
287a0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
287b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
287c0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
287d0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
287e0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
287f0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
28800 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
28810 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
28820 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
28830 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
28840 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
28850 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
28860 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
28870 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
28880 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
28890 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
288a0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
288b0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
288c0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
288d0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
288e0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
288f0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
28900 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
28910 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
28920 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
28930 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
28940 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
28950 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
28960 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
28970 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
28980 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
28990 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
289a0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
289b0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
289c0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
289d0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
289e0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
289f0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
28a00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
28a10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
28a20 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
28a30 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
28a40 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
28a50 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
28a60 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
28a70 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
28a80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28a90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
28aa0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
28ab0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
28ac0 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
28ad0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
28ae0 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
28af0 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
28b00 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
28b10 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
28b20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
28b30 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
28b40 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
28b50 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
28b60 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
28b70 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
28b80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
28b90 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
28ba0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
28bb0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
28bc0 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
28bd0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
28be0 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
28bf0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
28c00 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
28c10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28c20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
28c30 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
28c40 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
28c50 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
28c60 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
28c70 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
28c80 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
28c90 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
28ca0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
28cb0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
28cc0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
28cd0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
28ce0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
28d00 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
28d10 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
28d20 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
28d30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
28d40 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
28d50 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
28d60 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
28d70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
28d80 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
28d90 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
28da0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
28db0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
28dc0 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
28dd0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
28de0 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
28df0 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
28e00 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
28e10 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
28e20 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
28e30 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
28e40 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
28e50 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
28e60 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
28e70 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
28e80 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
28e90 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
28ea0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
28eb0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
28ec0 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
28ed0 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
28ee0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
28ef0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
28f00 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
28f10 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
28f20 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
28f30 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
28f40 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
28f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
28f60 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
28f70 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
28f80 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
28f90 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
28fa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
28fb0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
28fc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
28fd0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
28fe0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
28ff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
29000 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
29010 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
29020 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
29030 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
29040 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
29050 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
29060 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
29070 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
29080 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
29090 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
290a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
290b0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
290c0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
290d0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
290e0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
290f0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
29100 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
29110 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
29120 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
29130 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
29140 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
29150 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
29160 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
29170 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
29180 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
29190 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
291a0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
291b0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
291c0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
291d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
291e0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
291f0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
29200 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
29210 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
29220 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
29230 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
29240 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
29250 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
29260 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
29270 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
29280 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
29290 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
292a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
292b0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
292c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
292d0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
292e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
292f0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
29300 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
29310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29320 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
29330 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
29340 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
29350 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
29360 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
29370 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
29380 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
29390 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
293a0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
293b0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
293c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
293d0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
293e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
293f0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
29400 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
29410 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
29420 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
29430 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
29440 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
29450 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
29460 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
29470 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
29480 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
29490 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
294a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
294b0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
294c0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
294d0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
294e0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
294f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
29500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29510 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
29520 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
29530 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
29540 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
29550 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29560 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
29570 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
29580 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
29590 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
295a0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
295b0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
295c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
295d0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
295e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
295f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
29600 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
29610 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
29620 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
29630 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29640 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
29650 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
29660 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
29670 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
29680 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
29690 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
296a0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
296b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
296c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
296d0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
296e0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
296f0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
29700 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29710 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
29720 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
29730 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
29740 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
29750 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
29760 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29770 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
29780 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29790 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
297a0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
297b0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
297c0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
297d0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
297e0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
297f0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
29800 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
29810 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
29820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29830 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
29840 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29850 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
29860 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
29870 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
29880 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
29890 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
298a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
298b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
298c0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
298d0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
298e0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
298f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29900 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
29910 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
29920 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
29930 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
29940 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
29960 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
29970 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
29980 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
29990 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
299a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
299b0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
299c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
299d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
299e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
299f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
29a00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29a10 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
29a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29a30 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
29a40 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
29a50 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
29a60 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
29a70 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
29a80 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29a90 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
29aa0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
29ab0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29ac0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
29ad0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29ae0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
29af0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
29b00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
29b10 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
29b20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
29b30 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
29b40 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
29b50 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
29b60 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
29b70 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
29b80 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
29b90 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
29ba0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29bb0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
29bc0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
29bd0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
29be0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
29bf0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
29c00 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
29c10 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
29c20 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
29c30 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
29c40 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
29c50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
29c60 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
29c70 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
29c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29c90 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
29ca0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
29cb0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
29cc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29cd0 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
29ce0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
29cf0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
29d00 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
29d10 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
29d20 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
29d30 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
29d40 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
29d50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29d60 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
29d70 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
29d80 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
29d90 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
29da0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
29db0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
29dc0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
29dd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
29de0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
29df0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
29e00 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
29e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29e20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29e30 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
29e40 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
29e50 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
29e60 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
29e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29e80 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
29e90 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29ea0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
29eb0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
29ec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29ed0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
29ee0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29ef0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
29f00 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
29f10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
29f20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29f30 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
29f40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29f50 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29f60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29f70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29f80 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
29f90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29fa0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
29fb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29fc0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
29fd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
29fe0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
29ff0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a000 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
2a010 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
2a020 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
2a030 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a040 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a050 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
2a060 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
2a070 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
2a080 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
2a090 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
2a0a0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
2a0b0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2a0c0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
2a0d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
2a0e0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
2a0f0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
2a100 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
2a110 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
2a120 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2a130 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a140 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
2a150 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
2a160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2a170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a180 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2a190 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2a1a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2a1b0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2a1c0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2a1d0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
2a1e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2a1f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
2a200 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2a210 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2a220 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2a230 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2a240 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2a250 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2a260 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2a270 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2a280 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2a290 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a2a0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2a2b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a2c0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2a2d0 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
2a2e0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2a2f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2a300 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2a310 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2a320 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a330 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2a340 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2a350 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2a360 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2a370 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2a380 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2a390 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
2a3a0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2a3b0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2a3c0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2a3d0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2a3e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2a3f0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2a400 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
2a410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a420 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2a430 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2a440 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
2a450 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
2a460 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
2a470 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
2a480 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
2a490 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2a4a0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
2a4b0 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
2a4c0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
2a4d0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2a4e0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
2a4f0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2a500 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2a510 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2a520 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2a530 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2a540 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2a550 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2a560 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2a570 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2a580 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2a590 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2a5a0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2a5b0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2a5c0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2a5d0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2a5e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2a5f0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2a600 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2a610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a620 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2a630 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2a640 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2a650 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a660 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2a670 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2a680 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a690 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a6a0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2a6b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2a6c0 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
2a6d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a6e0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2a6f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2a700 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a710 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
2a720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2a730 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
2a740 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
2a750 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
2a760 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
2a770 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2a780 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
2a790 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2a7a0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
2a7b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a7c0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2a7d0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2a7e0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2a7f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2a800 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2a810 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2a820 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2a830 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a840 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2a850 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2a860 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2a870 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2a880 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2a890 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2a8a0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
2a8b0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
2a8c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a8d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a8e0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
2a8f0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a900 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
2a910 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2a920 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2a930 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a940 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2a950 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a960 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2a970 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2a980 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a990 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2a9a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2a9b0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2a9c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2a9d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a9e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2a9f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2aa00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2aa10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2aa20 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2aa30 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2aa40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2aa50 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2aa60 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2aa70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2aa80 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2aa90 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2aaa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2aab0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2aac0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2aad0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2aae0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2aaf0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2ab00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2ab10 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2ab20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2ab30 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2ab40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ab50 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2ab60 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2ab70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ab80 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2ab90 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2aba0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2abb0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2abc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2abd0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2abe0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2abf0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2ac00 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2ac10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ac20 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2ac30 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2ac40 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2ac50 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2ac60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ac70 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2ac80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2ac90 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2aca0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2acb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2acc0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2acd0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2ace0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2acf0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2ad00 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2ad10 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2ad20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ad30 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2ad40 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
2ad50 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2ad60 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
2ad70 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
2ad80 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
2ad90 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2ada0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
2adb0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2adc0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
2add0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2ade0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
2adf0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
2ae00 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
2ae10 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2ae20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ae30 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2ae40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ae50 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2ae60 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2ae70 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
2ae80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ae90 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63  n16(). ^In all c
2aea0 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
2aeb0 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
2aec0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2aed0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2aee0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2aef0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
2af00 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
2af10 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
2af20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
2af30 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6LE], or [SQLITE
2af40 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
2af50 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
2af60 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
2af70 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2af80 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
2af90 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2afa0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
2afb0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
2afc0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
2afd0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
2afe0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2aff0 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64  y. ^The.** third
2b000 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
2b010 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
2b020 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
2b030 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
2b040 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
2b050 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
2b060 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
2b070 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
2b080 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
2b090 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
2b0a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2b0b0 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
2b0c0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
2b0d0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2b0e0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
2b0f0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
2b100 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
2b110 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2b120 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
2b130 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
2b140 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
2b150 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
2b160 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
2b170 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
2b180 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
2b190 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2b1a0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
2b1b0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2b1c0 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
2b1d0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
2b1e0 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e  t anymore)..** ^
2b1f0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
2b200 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
2b210 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
2b220 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
2b230 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
2b240 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
2b250 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
2b260 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
2b270 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2b280 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2b290 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2b2a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2b2b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2b2c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  )..**.** ^The re
2b2d0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
2b2e0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
2b2f0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
2b300 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
2b310 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
2b320 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
2b330 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
2b340 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
2b350 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
2b360 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
2b370 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
2b380 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
2b390 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
2b3a0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
2b3b0 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70  stered.  The app
2b3c0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2b3d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
2b3e0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
2b3f0 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
2b400 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
2b410 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
2b420 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
2b430 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
2b440 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
2b450 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
2b460 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
2b470 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
2b480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
2b490 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2b4a0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
2b4b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b4c0 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
2b4d0 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
2b4e0 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
2b4f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
2b500 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
2b510 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
2b520 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2b530 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
2b540 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2b550 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
2b560 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
2b570 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
2b580 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
2b590 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
2b5a0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2b5b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2b5c0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73  ..** ^Collations
2b5d0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
2b5e0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
2b5f0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2b600 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
2b610 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
2b620 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2b630 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
2b640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b650 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
2b660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2b670 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
2b680 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
2b690 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b6a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b6b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b6c0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
2b6d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b6e0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2b6f0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2b700 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2b710 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2b720 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2b730 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2b740 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2b750 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2b760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2b770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2b780 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b790 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2b7a0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2b7b0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2b7c0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2b7d0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b7e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b7f0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
2b800 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2b810 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b820 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b830 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2b840 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2b850 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
2b860 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2b870 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2b880 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2b890 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2b8a0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2b8b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2b8c0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2b8d0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2b8e0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2b8f0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2b900 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2b910 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2b920 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2b930 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2b940 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2b950 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2b960 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2b970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b980 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2b990 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2b9a0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2b9b0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2b9c0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2b9d0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2b9e0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2b9f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2ba00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ba10 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2ba20 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2ba30 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2ba40 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2ba50 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2ba60 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2ba70 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2ba80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2ba90 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2baa0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2bab0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2bac0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2bad0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2bae0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2baf0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2bb00 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2bb10 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2bb20 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2bb40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2bb50 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2bb60 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2bb70 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2bb80 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2bb90 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2bba0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2bbb0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2bbc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2bbd0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2bbe0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2bbf0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2bc00 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2bc10 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2bc20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2bc30 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2bc40 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2bc50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2bc60 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2bc70 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2bc80 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2bc90 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2bca0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2bcb0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2bcc0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2bcd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2bce0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2bcf0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2bd00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2bd10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2bd20 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2bd30 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2bd40 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2bd50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bd60 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2bd70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2bd80 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2bd90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bda0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2bdb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bdc0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2bdd0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2bde0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2bdf0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2be00 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2be10 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2be20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2be30 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2be40 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2be50 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2be60 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2be70 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2be80 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
2be90 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
2bea0 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
2beb0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2bec0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2bed0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2bee0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2bef0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2bf00 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2bf10 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2bf20 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2bf30 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2bf40 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2bf50 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2bf60 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2bf70 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2bf80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2bf90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bfa0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2bfb0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2bfc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2bfd0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2bfe0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2bff0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2c000 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2c010 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2c020 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2c030 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2c040 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2c050 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2c060 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2c070 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2c080 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2c090 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2c0a0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2c0b0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2c0c0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2c0d0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2c0e0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2c0f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2c100 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2c110 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2c130 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2c140 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2c150 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2c160 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2c170 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2c180 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2c190 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2c1a0 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
2c1b0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2c1c0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2c1d0 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
2c1e0 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2c1f0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2c200 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
2c210 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c220 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2c230 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2c240 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2c250 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
2c260 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
2c270 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2c280 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2c290 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
2c2a0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2c2b0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2c2c0 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
2c2d0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2c2e0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2c2f0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
2c300 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
2c310 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2c320 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2c330 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2c340 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2c350 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2c360 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2c370 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
2c380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c   ^The sqlite3_sl
2c390 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
2c3a0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
2c3b0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
2c3c0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
2c3d0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2c3e0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2c3f0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2c400 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2c410 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  r..**.** ^If the
2c420 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2c430 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2c440 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2c450 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
2c460 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2c470 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2c480 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2c490 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
2c4a0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2c4b0 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  . ^The number of
2c4c0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
2c4d0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
2c4e0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
2c4f0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
2c500 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
2c510 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
2c520 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
2c530 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
2c540 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
2c550 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
2c560 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2c570 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2c580 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2c590 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2c5a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c5b0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2c5c0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2c5d0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2c5e0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2c5f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2c600 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2c610 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2c620 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2c630 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2c640 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2c650 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2c660 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2c670 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2c680 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2c690 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2c6a0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2c6b0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2c6c0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2c6d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2c6e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c6f0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2c700 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2c710 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2c720 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2c730 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2c740 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2c750 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2c760 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2c770 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2c780 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2c790 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2c7a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2c7b0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2c7c0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2c7d0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2c7e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2c7f0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2c800 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2c810 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2c820 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2c830 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2c840 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2c850 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2c860 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2c870 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2c880 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2c890 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2c8a0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2c8b0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2c8c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2c8d0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2c8e0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2c8f0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2c900 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2c910 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2c920 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2c930 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2c940 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2c950 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2c960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2c970 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2c980 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2c990 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2c9a0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2c9b0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2c9c0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2c9d0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2c9e0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2c9f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2ca00 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2ca10 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2ca20 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2ca30 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2ca40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2ca50 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2ca60 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2ca70 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2ca80 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2ca90 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2caa0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2cab0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2cac0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2cad0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2cae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2caf0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2cb00 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2cb10 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2cb20 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2cb30 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2cb40 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2cb50 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2cb60 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2cb70 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2cb80 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2cb90 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2cba0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2cbb0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2cbc0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2cbd0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2cbe0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2cbf0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2cc00 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2cc10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2cc20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2cc30 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2cc40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2cc50 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2cc60 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2cc70 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2cc80 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2cc90 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2cca0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2ccb0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2ccc0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2ccd0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2cce0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2ccf0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2cd00 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2cd10 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2cd20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2cd30 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2cd40 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2cd50 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2cd60 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2cd70 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2cd80 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2cd90 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2cda0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2cdb0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2cdc0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2cdd0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2cde0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2cdf0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2ce00 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2ce10 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2ce20 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2ce30 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2ce40 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2ce50 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2ce60 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2ce70 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2ce80 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2ce90 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2cea0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2ceb0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2cec0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2ced0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2cee0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2cef0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2cf00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2cf10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2cf20 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2cf30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cf40 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2cf50 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2cf60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2cf70 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2cf80 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2cf90 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2cfa0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2cfb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2cfc0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2cfd0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cfe0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2cff0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2d000 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2d010 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d020 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2d030 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2d040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2d050 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2d060 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2d070 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2d080 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d090 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2d0a0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2d0b0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2d0c0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2d0d0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2d0e0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2d0f0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2d100 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2d110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d120 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2d130 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d140 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2d150 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d160 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d170 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2d180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2d190 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2d1a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2d1b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d1c0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2d1d0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2d1e0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2d1f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2d200 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2d210 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2d220 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2d230 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2d240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d250 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2d260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d270 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2d280 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2d290 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2d2a0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2d2b0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2d2c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2d2d0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2d2e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d2f0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2d300 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2d310 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2d320 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2d330 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2d340 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2d350 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2d360 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2d370 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2d380 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2d390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d3a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2d3b0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2d3c0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2d3d0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2d3e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d3f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2d400 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2d410 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2d420 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2d430 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2d440 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2d450 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2d460 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2d470 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2d480 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2d490 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2d4a0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2d4b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2d4c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d4d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2d4e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2d4f0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2d500 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2d510 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2d520 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2d530 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2d540 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2d550 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2d560 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2d570 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2d580 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2d590 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2d5a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2d5b0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2d5c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d5d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2d5e0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2d5f0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2d600 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2d610 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2d620 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2d630 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2d640 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2d650 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2d660 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2d670 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2d680 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2d690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2d6a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2d6b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2d6c0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2d6d0 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2d6e0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2d6f0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2d700 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2d710 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2d720 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2d730 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d740 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2d750 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2d760 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2d770 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
2d780 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2d790 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2d7a0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2d7b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2d7c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2d7d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d7e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2d7f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2d800 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2d810 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2d820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d830 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2d840 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2d850 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2d860 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2d870 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2d880 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2d890 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2d8a0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2d8b0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2d8c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2d8d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d8e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2d8f0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2d900 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2d910 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2d920 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2d930 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2d940 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2d950 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
2d960 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
2d970 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
2d980 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2d990 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
2d9a0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
2d9b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
2d9c0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
2d9d0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
2d9e0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
2d9f0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
2da00 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
2da10 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2da20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2da30 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2da40 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2da50 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
2da60 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
2da70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2da80 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
2da90 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
2daa0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
2dab0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
2dac0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
2dad0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
2dae0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
2daf0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
2db00 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2db10 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2db20 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2db30 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2db40 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2db50 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2db60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2db70 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2db80 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2db90 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2dba0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2dbb0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
2dbc0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2dbd0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2dbe0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2dbf0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2dc00 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2dc10 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2dc20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dc30 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2dc40 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2dc50 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2dc60 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2dc70 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2dc80 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2dc90 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2dca0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2dcb0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2dcc0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2dcd0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2dce0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2dcf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dd00 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2dd10 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2dd20 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2dd30 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2dd40 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2dd50 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2dd60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2dd70 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2dd80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2dd90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2dda0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ddb0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2ddc0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2ddd0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2dde0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2ddf0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2de00 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2de10 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2de20 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2de30 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2de40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2de50 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2de60 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2de70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2de80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2de90 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2dea0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2deb0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2dec0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2ded0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2dee0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2def0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2df00 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2df10 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2df20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2df30 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2df40 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2df50 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2df60 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2df70 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2df80 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2df90 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2dfa0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2dfb0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2dfc0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2dfd0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2dfe0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2dff0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2e000 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2e010 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2e020 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2e030 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2e040 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2e050 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2e060 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2e070 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2e080 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2e090 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2e0a0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2e0b0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2e0c0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2e0d0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2e0e0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2e0f0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2e100 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2e110 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2e120 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2e130 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2e140 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2e150 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2e160 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2e170 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2e180 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2e190 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2e1a0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2e1b0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2e1c0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2e1d0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2e1e0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2e1f0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2e200 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2e210 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2e220 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2e230 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2e240 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2e250 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2e260 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2e270 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2e280 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2e290 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2e2a0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2e2b0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2e2c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2e2d0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2e2e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e2f0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2e300 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2e310 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2e320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e330 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2e340 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2e350 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2e360 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2e370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e380 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2e390 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2e3a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2e3b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2e3c0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2e3d0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2e3e0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2e3f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2e400 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e410 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2e420 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2e430 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2e440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2e450 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2e460 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2e470 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2e480 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e490 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2e4a0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
2e4b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
2e4c0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2e4d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
2e4e0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2e4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e500 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2e510 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2e520 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
2e530 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2e540 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2e550 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2e560 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2e570 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2e580 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
2e590 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2e5a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e5b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2e5c0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2e5d0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2e5e0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2e5f0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2e600 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2e610 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2e620 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
2e630 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2e640 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2e650 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e660 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2e670 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2e680 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2e690 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2e6a0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2e6b0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2e6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e6d0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2e6e0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2e6f0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2e700 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2e710 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2e720 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2e730 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2e740 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
2e750 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
2e760 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2e770 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2e780 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2e790 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2e7a0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2e7b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2e7c0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2e7d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2e7e0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2e7f0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2e800 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2e810 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2e820 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
2e830 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2e840 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2e850 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2e860 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2e870 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e880 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2e890 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2e8a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2e8b0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2e8c0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2e8d0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2e8e0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2e8f0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2e900 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2e910 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2e920 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
2e930 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2e940 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2e950 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
2e960 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
2e970 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
2e980 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
2e990 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2e9a0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
2e9b0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
2e9c0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2e9d0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2e9e0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2e9f0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2ea00 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2ea10 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2ea20 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2ea30 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2ea40 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2ea50 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2ea60 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2ea70 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2ea80 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2ea90 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
2eaa0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2eab0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
2eac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ead0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2eae0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
2eaf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb00 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2eb10 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2eb20 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
2eb30 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
2eb40 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
2eb50 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
2eb60 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
2eb70 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
2eb80 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
2eb90 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
2eba0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2ebb0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2ebc0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2ebd0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2ebe0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2ebf0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2ec00 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
2ec10 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
2ec20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2ec30 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2ec40 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
2ec50 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
2ec60 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
2ec70 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
2ec80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ec90 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2eca0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ecb0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2ecc0 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2ecd0 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2ece0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2ecf0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2ed00 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2ed10 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2ed20 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2ed30 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2ed40 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2ed50 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2ed60 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2ed70 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2ed80 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2ed90 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2eda0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2edb0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2edc0 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2edd0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2ede0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2edf0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2ee00 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2ee10 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2ee20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2ee30 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2ee40 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2ee50 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2ee60 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2ee70 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2ee80 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2ee90 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2eea0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2eeb0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2eec0 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2eed0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2eee0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2eef0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2ef00 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2ef10 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2ef20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2ef30 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2ef40 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2ef50 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2ef60 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2ef70 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2ef80 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2ef90 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2efa0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2efb0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2efc0 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2efd0 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2efe0 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2eff0 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2f000 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2f010 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2f020 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2f030 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2f040 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2f050 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2f060 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2f070 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2f080 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2f090 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2f0a0 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2f0b0 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2f0c0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2f0d0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2f0e0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2f0f0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2f100 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2f110 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2f120 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2f130 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2f140 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2f150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2f160 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2f170 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2f180 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2f190 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2f1a0 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2f1b0 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2f1c0 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2f1d0 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2f1e0 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2f1f0 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2f200 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2f210 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2f220 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2f230 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2f240 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2f250 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2f260 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2f270 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2f280 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2f290 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2f2a0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2f2b0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2f2c0 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2f2d0 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2f2e0 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2f2f0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2f300 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2f310 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2f320 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2f330 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2f340 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2f350 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2f360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2f380 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2f390 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2f3a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2f3b0 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2f3c0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2f3d0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2f3e0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2f3f0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2f400 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2f410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f420 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2f430 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2f440 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2f450 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2f460 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2f470 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2f480 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2f490 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2f4a0 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2f4b0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2f4c0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2f4d0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2f4e0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2f4f0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2f500 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2f510 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2f520 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2f530 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2f540 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2f550 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2f560 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2f570 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2f580 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2f590 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2f5a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2f5b0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2f5c0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2f5d0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2f5e0 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2f5f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2f600 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2f610 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2f620 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2f630 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2f640 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2f650 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2f660 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2f670 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2f680 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2f690 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2f6a0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2f6b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2f6c0 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2f6d0 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2f6e0 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
2f6f0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2f700 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2f710 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
2f720 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
2f730 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
2f740 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
2f750 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
2f760 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
2f770 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
2f780 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
2f790 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
2f7a0 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
2f7b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2f7c0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
2f7d0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f7e0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f7f0 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2f800 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2f810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
2f820 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2f830 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2f840 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2f850 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2f860 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
2f870 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2f880 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2f890 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
2f8a0 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
2f8b0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2f8c0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
2f8d0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2f8e0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2f8f0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2f900 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2f910 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2f920 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2f930 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2f940 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2f950 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2f960 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2f970 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2f980 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2f990 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2f9a0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2f9b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2f9c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f9d0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2f9e0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
2f9f0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
2fa00 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
2fa10 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
2fa20 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
2fa30 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
2fa40 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
2fa50 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2fa60 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2fa70 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
2fa80 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2fa90 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
2faa0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2fab0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2fac0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2fad0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2fae0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2faf0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2fb00 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2fb10 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2fb20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2fb30 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2fb40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2fb50 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2fb60 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2fb70 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2fb80 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2fb90 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2fba0 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
2fbb0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
2fbc0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2fbd0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2fbe0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2fbf0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2fc00 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2fc10 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2fc20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2fc30 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2fc40 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2fc50 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2fc60 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2fc70 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2fc80 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2fc90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2fca0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2fcb0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2fcc0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2fcd0 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
2fce0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2fcf0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2fd00 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2fd10 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2fd20 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2fd30 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2fd40 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2fd50 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
2fd60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
2fd70 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
2fd80 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
2fd90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2fda0 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
2fdb0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
2fdc0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
2fdd0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
2fde0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
2fdf0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
2fe00 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
2fe10 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
2fe20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2fe30 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
2fe40 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
2fe50 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2fe60 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
2fe70 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
2fe80 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
2fe90 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2fea0 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
2feb0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
2fec0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2fed0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
2fee0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
2fef0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2ff00 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
2ff10 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
2ff20 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
2ff30 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
2ff40 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2ff50 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
2ff60 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
2ff70 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
2ff80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2ff90 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2ffa0 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
2ffb0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
2ffc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
2ffd0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
2ffe0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2fff0 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
30000 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
30010 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
30020 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
30030 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30040 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
30050 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
30060 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
30070 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
30080 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
30090 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
300a0 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
300b0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
300c0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
300d0 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
300e0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
300f0 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
30100 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
30110 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
30120 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
30130 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30140 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
30150 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30160 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
30170 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
30180 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30190 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
301a0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
301b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
301c0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
301d0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
301e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
301f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
30200 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
30210 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
30220 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
30230 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30240 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
30250 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
30260 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
30270 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
30280 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
30290 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
302a0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
302b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
302c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
302d0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
302e0 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
302f0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
30300 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30310 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
30320 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
30330 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
30340 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
30350 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
30360 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
30370 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
30380 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
30390 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
303a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
303b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
303c0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
303d0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
303e0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
303f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
30400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
30410 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
30420 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
30430 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
30440 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
30450 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
30460 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
30470 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
30480 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
30490 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
304a0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
304b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
304c0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
304d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
304e0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
304f0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
30500 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
30510 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
30520 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
30530 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
30540 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
30550 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
30560 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
30570 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
30580 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
30590 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
305a0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
305b0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
305c0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
305d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
305e0 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
305f0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
30600 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
30610 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
30620 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
30630 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
30640 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
30650 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
30660 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
30670 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
30680 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30690 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
306a0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
306b0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
306c0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
306d0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
306e0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
306f0 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
30700 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
30710 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
30720 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
30730 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
30740 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
30750 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
30760 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
30770 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
30780 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
30790 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
307a0 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
307b0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
307c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
307d0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
307e0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
307f0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
30800 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
30810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30820 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
30830 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
30840 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
30850 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
30860 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
30870 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
30880 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
30890 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
308a0 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
308b0 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
308c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
308d0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
308e0 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
308f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
30900 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
30910 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
30920 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
30930 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
30940 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
30950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30960 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
30970 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
30980 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
30990 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
309a0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
309b0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
309c0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
309d0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
309e0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
309f0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
30a00 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
30a10 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
30a20 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
30a30 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
30a40 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
30a50 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
30a60 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
30a70 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
30a80 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
30a90 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
30aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30ab0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
30ac0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
30ad0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
30ae0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
30af0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
30b00 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
30b10 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
30b20 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
30b30 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
30b40 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
30b50 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
30b60 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
30b70 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
30b80 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
30b90 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
30ba0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
30bb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30bc0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
30bd0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
30be0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
30bf0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
30c00 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
30c10 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
30c20 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
30c30 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
30c40 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
30c50 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
30c60 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
30c70 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
30c80 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
30c90 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
30ca0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
30cb0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
30cc0 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
30cd0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
30ce0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
30cf0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
30d00 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
30d10 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
30d20 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
30d30 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
30d40 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
30d50 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
30d60 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
30d70 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
30d80 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30d90 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
30da0 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
30db0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
30dc0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
30dd0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
30de0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30df0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30e00 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
30e10 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
30e20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
30e30 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
30e40 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
30e50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
30e60 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
30e70 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
30e80 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
30e90 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
30ea0 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
30eb0 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
30ec0 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
30ed0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
30ee0 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
30ef0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30f00 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
30f10 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
30f20 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
30f30 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
30f40 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
30f50 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
30f60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30f70 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
30f80 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
30f90 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
30fa0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
30fb0 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
30fc0 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
30fd0 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
30fe0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
30ff0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
31000 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
31010 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
31020 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
31030 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
31040 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
31050 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
31060 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
31070 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
31080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31090 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
310a0 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
310b0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
310c0 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
310d0 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
310e0 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
310f0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
31100 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
31110 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31120 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
31130 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
31140 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
31150 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
31160 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
31170 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
31180 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
31190 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
311a0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
311b0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
311c0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
311d0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
311e0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
311f0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
31200 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
31210 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
31220 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
31230 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
31240 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
31250 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
31260 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
31270 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
31280 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
31290 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
312a0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
312b0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
312c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
312d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
312e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
312f0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
31300 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
31310 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
31320 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
31330 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
31340 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
31350 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
31360 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
31370 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
31380 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
31390 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
313a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
313b0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
313c0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
313d0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
313e0 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
313f0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
31400 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
31410 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
31420 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
31430 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
31440 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
31450 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
31460 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
31470 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
31480 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
31490 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
314a0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
314b0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
314c0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
314d0 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
314e0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
314f0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
31500 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31510 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
31520 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
31530 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31540 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
31550 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31560 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
31570 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
31580 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
31590 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
315a0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
315b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
315c0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
315d0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
315e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
315f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
31600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31610 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
31620 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
31630 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31640 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
31650 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
31660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
31670 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
31680 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
31690 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
316a0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
316b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
316c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
316d0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
316e0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
316f0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
31700 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
31710 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
31720 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
31730 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
31740 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
31750 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31760 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
31770 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
31780 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
31790 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
317a0 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
317b0 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
317c0 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
317d0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
317e0 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
317f0 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lds..**.** ^(The
31800 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
31810 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
31820 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
31830 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  aints of the for
31840 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f  m:.**.** <pre>co
31850 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72  lumn OP expr</pr
31860 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
31870 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
31880 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
31890 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
318a0 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
318b0 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
318c0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
318d0 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64  op.)^  ^(The ind
318e0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
318f0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
31900 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
31910 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
31920 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
31930 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
31940 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
31950 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
31960 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
31970 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
31980 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
31990 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
319a0 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
319b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
319c0 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
319d0 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
319e0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
319f0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
31a00 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
31a10 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
31a20 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
31a30 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
31a40 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
31a50 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
31a60 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
31a70 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
31a80 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
31a90 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
31aa0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
31ab0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
31ac0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
31ad0 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
31ae0 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
31af0 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
31b00 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
31b10 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
31b20 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
31b30 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
31b40 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
31b50 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
31b60 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
31b70 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
31b80 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
31b90 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
31ba0 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
31bb0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
31bc0 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
31bd0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
31be0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
31bf0 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
31c00 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
31c10 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
31c20 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
31c30 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
31c40 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
31c50 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
31c60 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
31c70 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
31c80 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
31c90 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
31ca0 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
31cb0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
31cc0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
31cd0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
31ce0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
31cf0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
31d00 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
31d10 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
31d20 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
31d30 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
31d40 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
31d50 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
31d60 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
31d70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
31d80 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
31d90 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
31da0 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
31db0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
31dc0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
31dd0 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
31de0 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
31df0 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
31e00 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
31e10 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
31e20 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
31e30 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
31e40 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
31e50 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
31e60 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
31e70 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
31e80 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
31e90 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
31ea0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
31eb0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
31ec0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
31ed0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
31ee0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
31ef0 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
31f00 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
31f10 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
31f20 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
31f30 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
31f40 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
31f50 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
31f60 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
31f70 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
31f80 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
31f90 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
31fa0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31fb0 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
31fc0 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
31fd0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
31fe0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
31ff0 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
32000 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
32010 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
32020 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
32030 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
32040 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
32050 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
32060 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
32070 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
32080 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
32090 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
320a0 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
320b0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
320c0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
320d0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
320e0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
320f0 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
32100 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
32110 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
32120 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
32130 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
32140 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
32150 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
32160 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
32170 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
32180 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
32190 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
321a0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
321b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
321c0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
321d0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
321e0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
321f0 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
32200 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
32210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
32220 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
32230 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
32240 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
32250 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
32260 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
32270 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
32280 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
32290 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
322a0 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
322b0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
322c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
322d0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
322e0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
322f0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
32300 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
32310 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
32320 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
32330 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
32340 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
32350 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
32360 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
32370 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
32380 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
32390 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
323a0 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
323b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
323c0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
323d0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
323e0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
323f0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
32400 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
32410 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
32420 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
32430 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
32440 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
32450 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
32460 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
32470 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
32480 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
32490 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
324a0 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
324b0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
324c0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
324d0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
324e0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
324f0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
32500 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
32510 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32520 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
32530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32540 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
32550 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
32560 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32570 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
32580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32590 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
325a0 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
325b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
325c0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
325d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
325e0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
325f0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
32600 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
32610 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
32620 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
32630 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
32640 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
32650 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
32660 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
32670 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a  e module] name..
32680 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  ** ^Module names
32690 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
326a0 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72  red before.** cr
326b0 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69  eating a new [vi
326c0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69  rtual table] usi
326d0 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  ng the module an
326e0 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61  d before using a
326f0 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
32700 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
32710 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
32720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c  **.** ^The modul
32730 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
32740 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
32750 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32760 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
32770 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
32780 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d  meter.  ^The nam
32790 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
327a0 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  is given by the 
327b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
327c0 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72  eter.  ^The thir
327d0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
327e0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74   pointer to.** t
327f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32800 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  n of the [virtua
32810 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
32820 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a     ^The fourth.*
32830 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
32840 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
32850 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
32860 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
32870 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
32880 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
32890 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
328a0 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
328b0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
328c0 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
328d0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
328e0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
328f0 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
32900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32910 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32920 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  le_v2() interfac
32930 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61  e has a fifth pa
32940 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
32950 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
32960 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
32970 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  r the pClientDat
32980 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  a.  ^SQLite will
32990 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
329a0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
329b0 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
329c0 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
329d0 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
329e0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
329f0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
32a00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
32a10 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20  ate_module().** 
32a20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75  interface is equ
32a30 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74  ivalent to sqlit
32a40 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32a50 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
32a60 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e  L.** destructor.
32a70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32a80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
32a90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
32ab0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
32ac0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
32ad0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
32ae0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
32af0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
32b00 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
32b10 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
32b20 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
32b30 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
32b40 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
32b50 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20  id *pClientData 
32b60 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
32b70 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
32b80 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
32b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32ba0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
32bb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
32bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32bd0 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
32be0 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
32bf0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
32c00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32c10 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
32c20 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
32c30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
32c40 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
32c50 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
32c60 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
32c70 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
32c80 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a,         /* Cl
32c90 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
32ca0 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
32cb0 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
32cc0 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
32cd0 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
32ce0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
32cf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32d00 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
32d10 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
32d20 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
32d30 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a  qlite3_vtab.**.*
32d40 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c  * Every [virtual
32d50 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69   table module] i
32d60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
32d70 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a  es a subclass.**
32d80 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
32d90 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
32da0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
32db0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  e.** of the [vir
32dc0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61  tual table].  Ea
32dd0 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
32de0 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
32df0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
32e00 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
32e10 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
32e20 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
32e30 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
32e40 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
32e50 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
32e60 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
32e70 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
32e80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32e90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75  ns..**.** ^Virtu
32ea0 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
32eb0 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
32ec0 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
32ed0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
32ee0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
32ef0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
32f00 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67  tf()] to zErrMsg
32f10 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68  .  The method sh
32f20 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72  ould.** take car
32f30 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72  e that any prior
32f40 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64   string is freed
32f50 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   by a call to [s
32f60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
32f70 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
32f80 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
32f90 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e  g to zErrMsg.  ^
32fa0 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
32fb0 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
32fc0 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
32fd0 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
32fe0 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
32ff0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
33000 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
33010 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
33020 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
33030 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
33040 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63  zeroed..*/.struc
33050 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b  t sqlite3_vtab {
33060 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
33070 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65  _module *pModule
33080 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65  ;  /* The module
33090 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61   for this virtua
330a0 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74  l table */.  int
330b0 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20   nRef;          
330c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
330d0 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a  NO LONGER USED *
330e0 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  /.  char *zErrMs
330f0 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g;              
33100 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73      /* Error mes
33110 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  sage from sqlite
33120 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20  3_mprintf() */. 
33130 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
33140 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33150 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
33160 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
33170 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
33180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
33190 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73  rtual Table Curs
331a0 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  or Object.** KEY
331b0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
331c0 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
331d0 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
331e0 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  }.**.** Every [v
331f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33200 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
33210 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
33220 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
33230 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
33240 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
33250 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
33260 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
33270 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
33280 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
33290 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
332a0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
332b0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
332c0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
332d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
332e0 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
332f0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
33300 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
33310 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
33320 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
33330 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
33340 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73  e] method.  Curs
33350 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
33360 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
33370 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
33380 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
33390 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
333a0 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
333b0 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
333c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
333d0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
333e0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
333f0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
33400 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
33410 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
33420 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
33430 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
33440 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
33450 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
33460 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
33470 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
33480 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
33490 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
334a0 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
334b0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
334c0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
334d0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
334e0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
334f0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
33500 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
33510 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
33520 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
33530 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
33540 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
33550 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
33560 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
33570 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65  ** ^The [xCreate
33580 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
33590 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a   methods of a.**
335a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
335b0 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69  module] call thi
335c0 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  s interface.** t
335d0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
335e0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
335f0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
33600 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
33610 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
33620 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
33630 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
33640 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
33650 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
33660 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
33670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33680 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
33690 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
336a0 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
336b0 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  (Virtual tables 
336c0 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
336d0 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
336e0 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
336f0 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
33700 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
33710 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
33720 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
33730 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
33740 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
33750 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
33760 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
33770 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
33780 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a   overloaded.)^.*
33790 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20  *.** ^(This API 
337a0 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f  makes sure a glo
337b0 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61  bal version of a
337c0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
337d0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e   particular.** n
337e0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f  ame and number o
337f0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69  f parameters exi
33800 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68  sts.  If no such
33810 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73   function exists
33820 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
33830 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61  API is called, a
33840 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
33850 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68   created.)^  ^Th
33860 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33870 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
33880 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
33890 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
338a0 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
338b0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
338c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
338d0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
338e0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
338f0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
33900 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
33910 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  ceholder functio
33920 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
33930 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61  erloaded.** by a
33940 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
33950 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33960 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
33970 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
33980 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
33990 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
339a0 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
339b0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
339c0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
339d0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
339e0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
339f0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
33a00 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
33a10 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
33a20 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
33a30 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
33a40 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
33a50 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
33a60 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
33a70 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
33a80 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
33a90 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
33aa0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
33ab0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
33ac0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
33ad0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
33ae0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
33af0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
33b00 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
33b10 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
33b20 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
33b30 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
33b40 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
33b50 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
33b60 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
33b70 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20  An Open BLOB.** 
33b80 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
33b90 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
33ba0 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
33bb0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
33bc0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
33bd0 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
33be0 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
33bf0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
33c00 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
33c10 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
33c20 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a  rformed..** ^Obj
33c30 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
33c40 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
33c50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
33c60 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
33c70 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
33c80 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
33c90 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  ]..** ^The [sqli
33ca0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
33cb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
33cc0 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
33cd0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
33ce0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
33cf0 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
33d00 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
33d10 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  BLOB..** ^The [s
33d20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
33d30 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
33d40 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
33d50 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62  of the BLOB in b
33d60 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
33d70 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
33d80 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
33d90 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
33da0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
33db0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
33dc0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  I/O.**.** ^(This
33dd0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
33de0 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s a [BLOB handle
33df0 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68   | handle] to th
33e00 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a  e BLOB located.*
33e10 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63  * in row iRow, c
33e20 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
33e30 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
33e40 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
33e50 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
33e60 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68  the same BLOB th
33e70 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
33e80 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
33e90 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
33ea0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
33eb0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
33ec0 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b   [rowid] = iRow;
33ed0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
33ee0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73  ** ^If the flags
33ef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
33f00 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
33f10 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
33f20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
33f30 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49  write access. ^I
33f40 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
33f50 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
33f60 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
33f70 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20  ..** ^It is not 
33f80 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
33f90 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
33fa0 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64  s part of an ind
33fb0 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a  ex or primary .*
33fc0 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e  * key for writin
33fd0 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  g. ^If [foreign 
33fe0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
33ff0 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74   are enabled, it
34000 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73   is .** not poss
34010 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
34020 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
34030 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b  rt of a [child k
34040 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  ey] for writing.
34050 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
34060 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
34070 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
34080 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
34090 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
340a0 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
340b0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
340c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
340d0 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61  se that.** appea
340e0 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20  rs after the AS 
340f0 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65  keyword when the
34100 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
34110 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
34120 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74  TACH]..** ^For t
34130 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
34140 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62   file, the datab
34150 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
34160 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50  n"..** ^For TEMP
34170 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
34180 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
34190 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  emp"..**.** ^(On
341a0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
341b0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
341c0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
341d0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
341e0 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
341f0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
34200 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
34210 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
34220 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
34230 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
34240 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68  ointer.)^.** ^Th
34250 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
34260 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34270 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
34280 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
34290 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
342a0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
342b0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
342c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
342d0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
342e0 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74  nctions. ^Note t
342f0 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
34300 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
34310 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
34320 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
34330 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
34340 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
34350 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
34360 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
34370 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
34380 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
34390 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
343a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  e..**.** ^(If th
343b0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f  e row that a BLO
343c0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20  B handle points 
343d0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62  to is modified b
343e0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  y an.** [UPDATE]
343f0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62  , [DELETE], or b
34400 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  y [ON CONFLICT] 
34410 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20  side-effects.** 
34420 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61  then the BLOB ha
34430 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61  ndle is marked a
34440 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20  s "expired"..** 
34450 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20  This is true if 
34460 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  any column of th
34470 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64  e row is changed
34480 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a  , even a column.
34490 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  ** other than th
344a0 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68  e one the BLOB h
344b0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e  andle is open on
344c0 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .)^.** ^Calls to
344d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
344e0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
344f0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
34500 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72  ] for.** a expir
34510 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66  ed BLOB handle f
34520 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75  ail with an retu
34530 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
34540 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28  TE_ABORT]..** ^(
34550 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
34560 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
34570 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
34580 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
34590 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  * rolled back by
345a0 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
345b0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
345c0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
345d0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
345e0 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
345f0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
34600 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
34610 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
34620 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
34630 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
34640 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
34650 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
34660 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
34670 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
34680 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
34690 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
346a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
346b0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
346c0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
346d0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
346e0 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
346f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
34700 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
34710 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
34720 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
34730 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
34740 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
34750 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
34760 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
34770 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
34780 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
34790 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
347a0 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
347b0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
347c0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
347d0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
347e0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
347f0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
34800 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
34810 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
34820 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
34830 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
34840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
34850 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
34860 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
34870 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
34880 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
34890 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
348a0 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
348b0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
348c0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
348d0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
348e0 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
348f0 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
34900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34910 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
34920 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
34930 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
34940 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
34950 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
34960 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
34970 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
34980 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
34990 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
349a0 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
349b0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
349c0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
349d0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
349e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
349f0 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
34a00 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
34a10 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
34a20 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
34a30 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
34a40 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
34a50 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
34a60 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
34a70 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
34a80 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
34a90 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
34aa0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
34ab0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
34ac0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
34ad0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
34ae0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
34af0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
34b00 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
34b10 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
34b20 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
34b30 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
34b40 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
34b50 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
34b60 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
34b70 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
34b80 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
34b90 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
34ba0 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
34bb0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
34bc0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
34bd0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
34be0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
34bf0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
34c00 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
34c10 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
34c20 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
34c30 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
34c40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34c50 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
34c60 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
34c70 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
34c80 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
34c90 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
34ca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34cb0 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
34cc0 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
34cd0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
34ce0 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
34cf0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
34d00 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
34d10 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
34d20 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
34d30 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
34d40 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
34d50 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
34d60 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
34d70 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
34d80 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
34d90 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
34da0 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
34db0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
34dc0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
34dd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34de0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
34df0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
34e00 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
34e10 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
34e20 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
34e30 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
34e40 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
34e50 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
34e60 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
34e70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
34e80 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
34e90 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
34ea0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
34eb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
34ec0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
34ed0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
34ee0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
34ef0 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
34f00 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
34f10 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34f20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f30 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
34f40 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
34f50 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
34f60 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
34f70 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
34f80 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
34f90 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
34fa0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34fb0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
34fc0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
34fd0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
34fe0 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
34ff0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
35000 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
35010 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
35020 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
35030 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
35040 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
35050 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
35060 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
35070 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35080 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35090 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
350a0 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
350b0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
350c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
350d0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
350e0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
350f0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
35100 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
35110 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
35120 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
35130 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
35140 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
35150 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
35160 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
35170 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
35180 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
35190 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
351a0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
351b0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
351c0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
351d0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
351e0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
351f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
35200 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
35210 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
35220 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
35230 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
35240 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
35250 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
35260 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35270 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
35280 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
35290 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
352a0 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
352b0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
352c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
352d0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
352e0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
352f0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
35300 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
35310 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
35320 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
35330 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
35340 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
35350 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
35360 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
35370 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
35380 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
35390 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
353a0 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
353b0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
353c0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
353d0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
353e0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
353f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35400 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
35410 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
35420 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
35430 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
35440 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
35450 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
35460 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
35470 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
35480 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
35490 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
354a0 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
354b0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
354c0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
354d0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
354e0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
354f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
35500 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
35510 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
35520 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
35530 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
35540 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
35550 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
35560 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35570 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
35580 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
35590 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
355a0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
355b0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
355c0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
355d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
355e0 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
355f0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
35600 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
35610 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
35620 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
35630 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
35640 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
35650 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
35660 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
35670 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
35680 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
35690 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
356a0 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
356b0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
356c0 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
356d0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
356e0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
356f0 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
35700 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
35710 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
35720 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
35730 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
35740 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
35750 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
35760 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
35770 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
35780 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
35790 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
357a0 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
357b0 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
357c0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
357d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
357e0 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
357f0 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
35800 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
35810 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
35820 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
35830 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
35840 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
35850 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
35860 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
35870 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
35880 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
35890 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
358a0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
358b0 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
358c0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
358d0 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
358e0 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
358f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
35900 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
35910 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
35920 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
35930 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
35940 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
35950 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
35960 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
35970 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
35980 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
35990 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
359a0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
359b0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
359c0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
359d0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
359e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
359f0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
35a00 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
35a10 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
35a20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35a30 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
35a40 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
35a50 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
35a60 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
35a70 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
35a80 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
35a90 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
35aa0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35ab0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
35ac0 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
35ad0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
35ae0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
35af0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
35b00 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
35b10 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
35b20 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
35b30 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
35b40 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
35b50 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
35b60 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
35b70 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
35b80 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
35b90 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
35ba0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
35bb0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
35bc0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
35bd0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
35be0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
35bf0 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
35c00 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
35c10 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
35c20 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
35c30 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
35c40 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
35c50 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
35c60 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
35c70 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
35c80 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
35c90 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
35ca0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
35cb0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
35cc0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35cd0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
35ce0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
35cf0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
35d00 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
35d10 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
35d20 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
35d30 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
35d40 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
35d50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
35d60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
35d70 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
35d80 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
35d90 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
35da0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
35db0 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
35dc0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
35dd0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
35de0 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
35df0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
35e00 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
35e10 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
35e20 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
35e30 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
35e40 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
35e50 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
35e60 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
35e70 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
35e80 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
35e90 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
35ea0 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
35eb0 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
35ec0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
35ed0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
35ee0 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
35ef0 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
35f00 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
35f10 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
35f20 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
35f30 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
35f40 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
35f50 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
35f60 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
35f70 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
35f80 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
35f90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
35fa0 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
35fb0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
35fc0 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
35fd0 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
35fe0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
35ff0 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
36000 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
36010 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
36020 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
36030 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
36040 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
36050 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
36060 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
36070 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
36080 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
36090 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
360a0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
360b0 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
360c0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
360d0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
360e0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
360f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
36100 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
36110 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
36120 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
36130 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
36140 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
36150 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
36160 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
36170 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
36180 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
36190 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
361a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
361b0 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
361c0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
361d0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
361e0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
361f0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
36200 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
36210 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
36220 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
36230 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
36240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
36250 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
36260 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
36270 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
36280 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
36290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
362a0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
362b0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
362c0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
362d0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
362e0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
362f0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
36300 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
36310 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
36320 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
36330 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
36340 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
36350 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
36360 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
36370 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
36380 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
36390 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
363a0 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
363b0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
363c0 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
363d0 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
363e0 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
363f0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
36400 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
36410 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
36420 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
36430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
36440 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
36450 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
36460 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
36470 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
36480 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
36490 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
364a0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
364b0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
364c0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
364d0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
364e0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
364f0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
36500 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36510 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
36520 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
36530 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
36540 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
36550 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
36560 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
36570 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
36580 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
36590 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
365a0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
365b0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
365c0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
365d0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
365e0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
365f0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
36600 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
36610 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
36620 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
36630 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
36640 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
36650 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
36660 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
36670 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
36680 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36690 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
366a0 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
366b0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
366c0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
366d0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
366e0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
366f0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
36700 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
36710 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
36720 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
36730 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
36740 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
36750 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
36760 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
36770 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36780 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
36790 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
367a0 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
367b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
367c0 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
367d0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
367e0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
367f0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36800 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
36810 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36820 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
36830 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
36840 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
36850 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
36860 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
36870 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
36880 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
36890 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
368a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
368b0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
368c0 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
368d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
368e0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
368f0 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
36900 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
36910 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
36920 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
36930 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
36940 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
36950 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
36960 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
36970 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
36980 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
36990 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
369a0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
369b0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
369c0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
369d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
369e0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
369f0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
36a00 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
36a10 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
36a20 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
36a30 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
36a40 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
36a50 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
36a60 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
36a70 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
36a80 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
36a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
36aa0 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
36ab0 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
36ac0 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
36ad0 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
36ae0 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
36af0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
36b00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
36b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
36b20 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
36b30 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
36b40 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
36b50 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
36b60 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
36b70 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
36b80 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36b90 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
36ba0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
36bb0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
36bc0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
36bd0 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
36be0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
36bf0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
36c00 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
36c10 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
36c20 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
36c30 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
36c40 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
36c50 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
36c60 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
36c70 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
36c80 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
36c90 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
36ca0 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
36cb0 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
36cc0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
36cd0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
36ce0 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
36cf0 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
36d00 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36d10 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
36d20 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
36d30 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
36d40 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
36d50 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
36d60 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
36d70 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
36d80 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
36d90 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
36da0 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
36db0 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
36dc0 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
36dd0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
36de0 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
36df0 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
36e00 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
36e10 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
36e20 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
36e30 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
36e40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
36e50 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
36e60 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
36e70 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
36e80 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
36e90 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
36ea0 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
36eb0 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
36ec0 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
36ed0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
36ee0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
36ef0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
36f00 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
36f10 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
36f20 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
36f30 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
36f40 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
36f50 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
36f60 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
36f70 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
36f80 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
36f90 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
36fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36fb0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36fc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
36fd0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
36fe0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
36ff0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
37000 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
37010 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
37020 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
37030 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
37040 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
37050 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
37060 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
37070 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
37080 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
37090 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
370a0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
370b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
370c0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
370d0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
370e0 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
370f0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
37100 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
37110 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
37120 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
37130 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
37140 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
37150 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
37160 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
37170 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
37180 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
37190 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
371a0 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
371b0 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
371c0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
371d0 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
371e0 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
371f0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
37200 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
37210 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
37220 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
37230 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
37240 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
37250 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
37260 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
37270 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
37280 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
37290 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
372a0 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
372b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
372c0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
372d0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
372e0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
372f0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
37300 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
37310 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
37320 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
37330 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
37340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
37350 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
37360 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
37370 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
37380 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
37390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
373a0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
373b0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
373c0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
373d0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
373e0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
373f0 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
37400 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
37410 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
37420 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
37430 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
37440 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
37450 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
37460 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
37470 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
37480 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
37490 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
374a0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
374b0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
374c0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
374d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
374e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
374f0 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
37500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
37510 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
37520 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
37530 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
37540 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
37550 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
37560 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
37570 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
37580 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
37590 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
375a0 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
375b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
375c0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
375d0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
375e0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
375f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
37600 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
37610 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
37620 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
37630 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
37640 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
37650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37660 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
37670 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
37680 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
37690 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
376a0 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
376b0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
376c0 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
376d0 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
376e0 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
376f0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
37700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37710 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
37720 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
37730 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
37740 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
37750 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
37760 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
37770 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37780 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
37790 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
377a0 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
377b0 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
377c0 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
377d0 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
377e0 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
377f0 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
37800 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
37810 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
37820 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
37830 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
37840 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
37850 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
37860 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
37870 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
37880 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
37890 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
378a0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
378b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
378c0 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
378d0 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
378e0 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
378f0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
37900 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
37910 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
37920 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
37930 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
37940 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
37950 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
37960 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
37970 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
37980 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
37990 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
379a0 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
379b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
379c0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
379d0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
379e0 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
379f0 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
37a00 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
37a10 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
37a20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37a30 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
37a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
37a50 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
37a60 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
37a70 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
37a80 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
37a90 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
37aa0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
37ab0 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
37ac0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
37ad0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
37ae0 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
37af0 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
37b00 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
37b10 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
37b20 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
37b30 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
37b40 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
37b50 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
37b60 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
37b70 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
37b80 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
37b90 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
37ba0 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
37bb0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
37bc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37bd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
37be0 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
37bf0 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
37c00 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
37c10 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
37c20 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
37c30 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
37c40 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
37c50 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
37c60 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
37c70 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
37c80 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
37c90 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
37ca0 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
37cb0 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
37cc0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37cd0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
37ce0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
37cf0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
37d00 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
37d10 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37d20 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37d30 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
37d40 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
37d50 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
37d60 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37d70 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
37d80 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
37d90 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
37da0 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
37db0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37dc0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37dd0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
37de0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
37df0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
37e00 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
37e10 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
37e20 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
37e30 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
37e40 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
37e50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
37e60 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
37e70 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
37e80 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
37e90 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
37ea0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
37eb0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
37ec0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
37ed0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
37ee0 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
37ef0 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
37f00 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
37f10 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
37f20 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
37f30 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
37f40 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
37f50 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
37f60 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
37f70 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
37f80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
37f90 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
37fa0 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
37fb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
37fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
37fd0 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
37fe0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
37ff0 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
38000 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
38010 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
38020 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
38030 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
38040 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
38050 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
38060 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
38070 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
38080 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
38090 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
380a0 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
380b0 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
380c0 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
380d0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
380e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
380f0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
38100 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
38110 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
38120 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
38130 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
38140 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
38150 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
38160 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
38170 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
38180 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
38190 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
381a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
381b0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
381c0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
381d0 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
381e0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
381f0 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
38200 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
38210 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
38220 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
38230 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
38240 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
38250 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
38260 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
38270 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
38280 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
38290 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
382a0 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
382b0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
382c0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
382d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
382e0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
382f0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
38300 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
38310 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
38320 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
38330 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
38340 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
38350 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
38360 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
38370 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
38380 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
38390 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
383a0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
383b0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
383c0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
383d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
383e0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
383f0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
38400 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
38410 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
38420 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
38430 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
38440 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
38450 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
38460 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
38470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38480 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
38490 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
384a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
384b0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
384c0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
384d0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
384e0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
384f0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
38500 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
38510 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
38520 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
38530 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
38540 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
38550 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
38560 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
38570 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
38580 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
38590 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
385a0 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
385b0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
385c0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
385d0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
385e0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
385f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
38600 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
38610 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
38620 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
38630 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
38640 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
38650 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
38660 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
38670 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
38680 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
38690 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
386a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
386b0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
386c0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
386d0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
386e0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
386f0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
38700 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
38710 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
38720 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
38730 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
38740 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
38750 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
38760 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
38770 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
38780 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
38790 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
387a0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
387b0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
387c0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
387d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
387e0 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
387f0 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
38800 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
38810 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
38820 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
38830 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
38840 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
38850 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
38860 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
38870 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
38880 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38890 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
388a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
388b0 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
388c0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
388d0 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
388e0 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75