System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e3d2c50856e64ad21b44c5215132f5db91236880:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 36 2e 31 22 0a 23 64 65 66 69 6e 65 20  .7.6.1".#define 
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1040: 55 4d 42 45 52 20 33 30 30 37 30 30 36 0a 23 64  UMBER 3007006.#d
1050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1060: 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31  RCE_ID      "201
1070: 31 2d 30 34 2d 32 37 20 31 38 3a 30 38 3a 34 32  1-04-27 18:08:42
1080: 20 31 62 64 31 34 38 34 63 64 37 65 30 39 37 30   1bd1484cd7e0970
1090: 39 64 38 37 61 61 38 34 62 38 32 65 38 37 35 39  9d87aa84b82e8759
10a0: 37 64 30 30 61 34 31 36 32 22 0a 0a 2f 2a 0a 2a  7d00a4162"../*.*
10b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
10c0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
10d0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20  sion Numbers.** 
10e0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
10f0: 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74  3_version, sqlit
1100: 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a  e3_sourceid.**.*
1110: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1120: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
1130: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1140: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
1150: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
1160: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1170: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
1180: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1190: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
11a0: 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73  s.** but are ass
11b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
11c0: 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64   library instead
11d0: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66   of the header f
11e0: 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73  ile.  ^(Cautious
11f0: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1200: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73  might include as
1210: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
1220: 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69  s in their appli
1230: 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72  cation to.** ver
1240: 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20  ify that values 
1250: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74  e interfaces mat
1270: 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ch the macros in
1280: 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20  .** the header, 
1290: 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20  and thus insure 
12a0: 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  that the applica
12b0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  tion is.** compi
12c0: 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e  led with matchin
12d0: 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65  g library and he
12e0: 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  ader files..**.*
12f0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1300: 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73  re>.** assert( s
1310: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1320: 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49  n_number()==SQLI
1330: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1340: 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  R );.** assert( 
1350: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73  strcmp(sqlite3_s
1360: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45  ourceid(),SQLITE
1370: 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29  _SOURCE_ID)==0 )
1380: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1390: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
13a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
13b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
13c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
13e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
13f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1400: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1410: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1420: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1430: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1450: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1470: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1480: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1490: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
14a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
14b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
14c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
14d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
14e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
14f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1500: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1510: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1520: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1530: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1540: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1550: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1560: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1570: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1580: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1590: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
15a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
15b0: 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f  urceid() functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20  n returns .** a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
15e0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f  ing constant who
15f0: 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  se value is the 
1600: 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20  same as the .** 
1610: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
1620: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
1630: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
1640: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1650: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
1660: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1670: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1680: 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
1690: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
16a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
16b0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16c0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
16d0: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
16e0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16f0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1700: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1710: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1720: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1730: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1740: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1750: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1760: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1770: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1780: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1790: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
17a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
17b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
17c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
17d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
17e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
17f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1800: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1810: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1820: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1830: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1840: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1850: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1860: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1870: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1880: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1890: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
18a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
18b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
18c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
18d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
18e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
18f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1900: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1910: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1920: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1930: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1940: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1950: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1960: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1970: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1980: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1990: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
19a0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
19b0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
19c0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19d0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
19e0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
19f0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1a00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1a10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1a30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1a40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1a50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1a60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1a70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1aa0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1ab0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1ac0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1ad0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1ae0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1af0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1b00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1b10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1b20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1b30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1b40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1b50: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
1b60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  t sqlite3_compil
1b70: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e  eoption_used(con
1b80: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d  st char *zOptNam
1b90: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  e);.SQLITE_API c
1ba0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1bb0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1bc0: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
1bd0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1be0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1bf0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1c00: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1c10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c20: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1c30: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1c40: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1c50: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1c60: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1c70: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1c80: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c90: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1ca0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1cb0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1cc0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1cd0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1ce0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1cf0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1d00: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1d10: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1d20: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d30: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1d40: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1d50: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1d60: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1d70: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1d80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d90: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1da0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1db0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1dc0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1dd0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1de0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1df0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1e00: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1e10: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1e20: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1e30: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1e40: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1e50: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1e60: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1e70: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1e80: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e90: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1ea0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1eb0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1ec0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1ed0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1ee0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1ef0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1f00: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1f10: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1f20: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1f30: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1f40: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1f50: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1f60: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1f70: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1f80: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1fa0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1fb0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1fc0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1fd0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1fe0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1ff0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2000: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
2010: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
2020: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
2030: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
2040: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2050: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
2060: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2070: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2080: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2090: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
20a0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
20b0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
20c0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
20d0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
20e0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
20f0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2100: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2110: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2120: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2130: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
2140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
2150: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2160: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2170: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2180: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2190: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
21a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
21b0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
21c0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
21d0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
21e0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
21f0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2210: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2220: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2230: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2240: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2250: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2260: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2270: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2280: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2290: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
22a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
22b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
22c0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
22d0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
22e0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
22f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2300: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2310: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2320: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2340: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2350: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2360: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2370: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2380: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2390: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
23a0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
23b0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
23c0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
23d0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
23e0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
23f0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2400: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2410: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2430: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2440: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2450: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2460: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2470: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2480: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
2490: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
24a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
24b0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
24c0: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
24d0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
24e0: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24f0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2500: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2510: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2520: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2530: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
2540: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
2550: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
2560: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2570: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
2580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
2590: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
25a0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
25b0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
25c0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
25d0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
25e0: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
25f0: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2600: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2610: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2620: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2630: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2640: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2650: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2660: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2670: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2680: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
2690: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
26a0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
26b0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
26c0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
26d0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
26e0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
26f0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2700: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2710: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2720: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2730: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2740: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2750: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
2760: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
2770: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
2780: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
2790: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
27a0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
27b0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
27c0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
27d0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
27e0: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
27f0: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2800: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2810: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2820: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2830: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
2840: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
2850: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2860: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
2870: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
28a0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
28b0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
28c0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
28d0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
28e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28f0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2900: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2910: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2920: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2930: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2940: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
2950: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
2960: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
2970: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
2980: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
29a0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
29b0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
29c0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
29d0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
29e0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
29f0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2a00: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2a10: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2a20: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2a30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
2a40: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
2a50: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
2a60: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
2a70: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2a80: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
2a90: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2aa0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2ac0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2ad0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2ae0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2af0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2b00: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2b10: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2b20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2b30: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2b40: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2b50: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2b60: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2b70: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2b80: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2b90: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2ba0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2bb0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2bc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2bd0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2be0: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2bf0: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2c00: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2c10: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2c20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2c30: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2c40: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2c50: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2c60: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2c70: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2c80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c90: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2ca0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2cb0: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2cc0: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2cd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2ce0: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2cf0: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2d00: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2d10: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2d20: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2d30: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2d40: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2d50: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2d60: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2d70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2d80: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2d90: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2da0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2db0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2dc0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2dd0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2de0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2e00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2e10: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2e20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2e30: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2e40: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2e50: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2e60: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2e70: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2e80: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2e90: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2ea0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2eb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
2ec0: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ite3 *);../*.** 
2ed0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
2ee0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2ef0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
2f00: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
2f10: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
2f20: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
2f30: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
2f40: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
2f50: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
2f60: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
2f70: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
2f80: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
2f90: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
2fa0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
2fb0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
2fc0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
2fd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2fe0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
2ff0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3000: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3010: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3020: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3030: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
3040: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3050: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
3060: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
3070: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
3080: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
3090: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
30a0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
30b0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
30c0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
30d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
30e0: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
30f0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3100: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3110: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3120: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3130: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
3140: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
3150: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
3160: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
3170: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
3180: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
3190: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
31a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
31b0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
31c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31e0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
31f0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3200: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3210: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3220: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3230: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
3240: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3250: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 6f 20 73 71  ment to.** to sq
3260: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3270: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3280: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3290: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
32a0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
32b0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
32c0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
32e0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
32f0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3300: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3310: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3320: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3330: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3340: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3350: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3360: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3370: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3380: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3390: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
33a0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
33b0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
33c0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
33d0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
33e0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
33f0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3400: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3410: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3420: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3430: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3440: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3450: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3460: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3470: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3480: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3490: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
34a0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
34b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34c0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
34d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
34e0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
34f0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3500: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3510: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3520: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
3530: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3540: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3550: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3560: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3570: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3580: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3590: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
35a0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
35b0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
35c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
35d0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
35e0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
35f0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3600: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3610: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3620: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3630: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3640: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3650: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3660: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3670: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3680: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3690: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
36a0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
36b0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
36c0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
36d0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
36e0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
36f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3700: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3710: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3720: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3730: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3740: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3750: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3760: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3770: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3780: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3790: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
37a0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
37b0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37c0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
37d0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
37e0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
37f0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3800: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3810: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3820: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3830: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3840: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3850: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3860: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3870: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3880: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3890: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
38a0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
38b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
38c0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
38d0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
38e0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
38f0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3900: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3910: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3920: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3930: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3940: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3950: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3960: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3970: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3980: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3990: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
39a0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
39b0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
39c0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
39d0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
39e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
39f0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3a00: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3a10: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3a20: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3a30: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3a40: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3a50: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3a60: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3a90: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3aa0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ab0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3ac0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3ad0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3ae0: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
3af0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
3b00: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
3b10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3b20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b30: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
3b50: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
3b60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3b70: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
3b80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3b90: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
3ba0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
3bb0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
3bc0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
3bd0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3be0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3bf0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
3c00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
3c10: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3c20: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3c50: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3c60: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3c90: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3ca0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3cb0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3cc0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3cd0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3ce0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d10: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
3d20: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
3d30: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
3d40: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3d60: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3d70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d90: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3da0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3db0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3dc0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3dd0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3de0: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
3df0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
3e00: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
3e10: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
3e20: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
3e30: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
3e40: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3e50: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3e60: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
3f00: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
3f10: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3f20: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
3f30: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
3f40: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3f60: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3f70: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3f80: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3fa0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3fb0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3fc0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3fd0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3fe0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3ff0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4000: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4010: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4020: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4030: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4040: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4050: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4070: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4080: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4090: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40b0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
40c0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
40d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
40e0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
40f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4100: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4110: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4130: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4140: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4150: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4160: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4180: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4190: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
41a0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
41b0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
41c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
41d0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
41e0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
41f0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4200: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4220: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4230: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4240: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4250: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4260: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4270: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4280: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4290: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
42a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
42b0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
42c0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
42d0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
42e0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
42f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4300: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4310: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4320: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4330: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4340: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4350: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4360: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4370: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4390: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
43a0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
43b0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
43c0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
43d0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
43e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
43f0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4400: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4410: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4420: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4430: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4450: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4460: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4470: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4480: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4490: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
44a0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
44b0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
44c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44d0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
44e0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
44f0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4510: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4520: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4530: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4540: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4560: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4570: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4580: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4590: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
45a0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
45b0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
45c0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
45e0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
45f0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4600: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4610: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4630: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4640: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4650: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4660: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4680: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4690: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
46a0: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
46b0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
46c0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
46d0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
46e0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
46f0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4700: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4710: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4720: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4730: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4740: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4750: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4760: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4770: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4780: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4790: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
47a0: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
47b0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
47c0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
47d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
47e0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
47f0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4800: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4810: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4820: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4830: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4840: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4850: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4860: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4870: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4880: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4890: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
48a0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
48b0: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
48c0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
48d0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
48e0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
48f0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4900: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4910: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4920: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4930: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4940: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4950: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4960: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4970: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4980: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4990: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
49a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49b0: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
49c0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
49d0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
49e0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
49f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4a00: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4a10: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4a20: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4a30: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4a40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a50: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4a60: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4a70: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4a80: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4a90: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4aa0: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4ab0: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ac0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4ad0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ae0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4af0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4b00: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4b10: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4b20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4b30: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4b40: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4b50: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4b60: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4b70: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4b80: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4b90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4ba0: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4bb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4bc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4bd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4be0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4bf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c10: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4c30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4c40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4c50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4c60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4c70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
4c80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c90: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
4cb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
4cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4cd0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
4ce0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cf0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
4d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4d10: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
4d20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4d30: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
4d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d50: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
4d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d70: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d90: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
4da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4db0: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
4dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4dd0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
4de0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4df0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
4e00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e10: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
4e20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e30: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
4e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e50: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
4e60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e70: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
4e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e90: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
4ea0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4eb0: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
4ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ed0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
4ee0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
4ef0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
4f00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f10: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
4f20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f30: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
4f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f50: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
4f60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f70: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
4f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f90: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
4fa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fb0: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
4fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fd0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
4fe0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4ff0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5010: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5020: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5030: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5050: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5060: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5070: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5090: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
50a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50b0: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
50c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50d0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
50e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50f0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5110: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5120: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5130: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5150: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5160: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5170: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5190: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
51a0: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
51b0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
51c0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
51d0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
51e0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
51f0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5200: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5210: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5220: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5230: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5240: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5250: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5260: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5270: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78  rameter to the x
5280: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74  Open method of t
5290: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
52a0: 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  fs] object..*/.#
52b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
52c0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
52d0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
52e0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
52f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5310: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
5320: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
5330: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5340: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5360: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
5370: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5380: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5390: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
53b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
53c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
53d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
53f0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5400: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
5410: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5430: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
5440: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
5450: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5470: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
5480: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
5490: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
54b0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
54c0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
54d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
54f0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
5500: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
5510: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5530: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
5540: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
5550: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5570: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
5580: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
5590: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
55a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
55b0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
55c0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
55d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
55e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
55f0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
5600: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
5610: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5630: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
5640: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
5650: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5660: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5680: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
5690: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
56a0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
56b0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
56d0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
56e0: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
56f0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5700: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5720: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
5730: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
5740: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5750: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5770: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
5780: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
5790: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
57a0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
57b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
57c0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
57d0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
57e0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
57f0: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
5800: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
5810: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
5820: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
5830: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
5840: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
5850: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
5860: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
5870: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
5880: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5890: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
58a0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
58b0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
58c0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
58d0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
58e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
58f0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5900: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5920: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5930: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5940: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5950: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5960: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5970: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5980: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5990: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
59a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
59b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
59c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
59d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
59e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
59f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5a00: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
5a10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
5a30: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
5a40: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
5a50: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
5a60: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5a70: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5a80: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5a90: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5aa0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5ab0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5ac0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5ad0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5ae0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5af0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5b00: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
5b10: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5b20: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5b30: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5b40: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b60: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
5b70: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5b90: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
5ba0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5bb0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5bc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5bd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5be0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c00: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5c10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c20: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
5c30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
5c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c50: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5c60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c70: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
5c80: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5ca0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5cb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5cc0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5cd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ce0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
5cf0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
5d00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d10: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
5d20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d30: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
5d40: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5d50: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
5d60: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
5d70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5d80: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
5da0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5db0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
5dc0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
5dd0: 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a  x00000800../*.**
5de0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
5df0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
5e00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
5e10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
5e20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5e30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
5e40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
5e50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
5e60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5e70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
5e80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5e90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5ea0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
5eb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
5ec0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
5ed0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
5ee0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
5ef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5f00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
5f10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
5f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
5f30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
5f40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5f50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
5f60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
5f70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
5f80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
5f90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
5fa0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
5fb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
5fc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5fd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
5fe0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
5ff0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6000: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6010: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6020: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6030: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6040: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6050: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6060: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6070: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6080: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6090: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
60a0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
60b0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
60c0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
60d0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
60e0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
60f0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6100: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6110: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6120: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6130: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6140: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6150: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6160: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6170: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6180: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6190: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
61a0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
61b0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
61c0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
61d0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
61e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
61f0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6200: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6210: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6220: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6230: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6240: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6250: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6260: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6270: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6280: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6290: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
62a0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
62b0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
62c0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
62d0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
62e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
62f0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6300: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6310: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6320: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
6330: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
6340: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
6350: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
6360: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
6370: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
6380: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6390: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
63a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
63b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
63c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
63d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
63e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
63f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6400: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
6410: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
6420: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
6430: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
6440: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
6450: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
6460: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
6470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6480: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6490: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
64a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
64b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
64c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
64d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
64e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
64f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6500: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
6510: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
6520: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
6530: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
6540: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
6550: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
6560: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
6570: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
6580: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6590: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
65a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
65b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
65c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
65d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
65e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
65f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
6600: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
6610: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
6620: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
6630: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6640: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6650: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
6660: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
6670: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
6680: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6690: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
66a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
66b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
66c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
66d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
66e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
66f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
6700: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
6710: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
6720: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
6730: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6740: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
6750: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
6760: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
6770: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
6780: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6790: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  s] xOpen method 
67a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
67b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
67c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
67d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
67e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
67f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6800: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6810: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
6820: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6830: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
6840: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
6850: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
6860: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
6870: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6880: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6890: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
68a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
68b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
68c0: 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20  ** If the xOpen 
68d0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
68e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
68f0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
6900: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
6910: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
6920: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
6930: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
6940: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
6950: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
6960: 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20   xOpen reported 
6970: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
6980: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
6990: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
69a0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
69b0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
69c0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20  xOpen.** is for 
69d0: 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74  the xOpen to set
69e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
69f0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
6a00: 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  nt to NULL..**.*
6a10: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
6a20: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
6a30: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
6a40: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
6a50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
6a60: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
6a70: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
6a80: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
6a90: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
6aa0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
6ab0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6ac0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
6ad0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6ae0: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6af0: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6b00: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6b10: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6b20: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6b30: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6b40: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6b50: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6b60: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6b70: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6b80: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
6b90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6ba0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
6bb0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6bc0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6bd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6be0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6bf0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6c00: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6c10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6c20: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6c30: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6c40: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6c50: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
6c60: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
6c70: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
6c80: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
6c90: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
6ca0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
6cb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
6cc0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
6cd0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
6ce0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
6cf0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
6d00: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
6d10: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
6d20: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
6d30: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
6d40: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
6d50: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
6d60: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
6d70: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
6d80: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6d90: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
6da0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
6db0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
6dc0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
6dd0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
6de0: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
6df0: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
6e00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
6e10: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
6e20: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
6e30: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
6e40: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
6e50: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
6e60: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
6e70: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
6e80: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
6e90: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
6ea0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
6eb0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
6ec0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
6ed0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
6ee0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
6ef0: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
6f00: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
6f10: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
6f20: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
6f30: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
6f40: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
6f50: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
6f60: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
6f70: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
6f80: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
6f90: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
6fa0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
6fb0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
6fc0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
6fd0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
6fe0: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
6ff0: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7000: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7010: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7020: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
7030: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7040: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
7050: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
7060: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
7070: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7080: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7090: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
70a0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
70b0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
70c0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
70d0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
70e0: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
70f0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7100: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
7110: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
7120: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7130: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
7140: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
7150: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
7160: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
7170: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
7180: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
7190: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
71a0: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
71b0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
71c0: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
71d0: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
71e0: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
71f0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
7200: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
7210: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
7220: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
7230: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
7240: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7250: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
7260: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
7270: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
7280: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
7290: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
72a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
72b0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
72c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
72d0: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
72e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72f0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
7300: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7310: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
7320: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7330: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
7340: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7350: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
7360: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7370: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
7380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7390: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
73a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
73b0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
73c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
73d0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
73e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
73f0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7400: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
7410: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
7420: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
7430: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
7440: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
7450: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
7460: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
7470: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
7480: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
7490: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
74a0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
74b0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
74c0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
74d0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
74e0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
74f0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
7500: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
7510: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
7520: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7530: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
7540: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
7550: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
7560: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
7570: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
7580: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
7590: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
75a0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
75b0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
75c0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
75d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
75e0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
75f0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
7600: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
7610: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
7620: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
7630: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
7640: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
7650: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
7660: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
7670: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
7680: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
7690: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
76a0: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
76b0: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
76c0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
76d0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
76e0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
76f0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
7700: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
7710: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
7720: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7730: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
7740: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
7750: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
7760: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7770: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7780: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
7790: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
77a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
77b0: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
77c0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
77d0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
77e0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
77f0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
7800: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
7810: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
7820: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7830: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
7840: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
7850: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
7860: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
7870: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
7880: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
7890: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
78a0: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
78b0: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
78c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
78d0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
78e0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
78f0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
7900: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
7910: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
7920: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7930: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
7940: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
7950: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
7960: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
7970: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
7980: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
7990: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
79a0: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
79b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
79c0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
79d0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
79e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79f0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
7a00: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
7a10: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
7a20: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
7a30: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7a40: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
7a50: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
7a60: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7a70: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
7a80: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
7a90: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
7aa0: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
7ab0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7ac0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
7ad0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
7ae0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
7af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7b00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
7b10: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
7b20: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
7b30: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
7b40: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7b50: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
7b60: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
7b70: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7b80: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
7b90: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
7ba0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7bb0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
7bc0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
7bd0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7be0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
7bf0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
7c00: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7c10: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7c20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7c30: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7c40: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7c50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7c60: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
7c70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7c80: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7c90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7ca0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
7cb0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
7cc0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
7ce0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
7cf0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
7d00: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
7d10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7d20: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
7d30: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
7d40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7d50: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
7d60: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
7d70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7d80: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
7d90: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
7da0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
7db0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
7dc0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
7dd0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
7de0: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
7df0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
7e00: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
7e10: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
7e20: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
7e30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
7e40: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
7e50: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
7e60: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
7e70: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
7e80: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
7e90: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
7ea0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
7eb0: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
7ec0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
7ed0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
7ee0: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
7ef0: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
7f00: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
7f10: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
7f20: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
7f30: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
7f40: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
7f50: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
7f60: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
7f70: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
7f80: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
7f90: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
7fa0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
7fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7fc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7fd0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
7fe0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
7ff0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8000: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8010: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8020: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8030: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8040: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
8050: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
8060: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8070: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8080: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8090: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
80a0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
80b0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
80c0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
80d0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
80e0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
80f0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8100: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8110: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8120: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8130: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8140: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
8150: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
8160: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8170: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8180: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8190: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
81a0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
81b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
81c0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
81d0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
81e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
81f0: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
8200: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
8210: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
8220: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
8230: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8240: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
8250: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
8260: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
8270: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28  mation..**.** ^(
8280: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8290: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
82a0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
82b0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
82c0: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
82d0: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
82e0: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
82f0: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
8300: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
8310: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
8320: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
8330: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8340: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
8350: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
8360: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
8370: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
8380: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
8390: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
83a0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
83b0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
83c0: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
83d0: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
83e0: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
83f0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8400: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
8410: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
8420: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
8430: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
8440: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
8450: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8460: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
8470: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
8480: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
8490: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
84a0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
84b0: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
84c0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
84d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
84e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
84f0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
8500: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
8510: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
8520: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
8530: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
8540: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
8550: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
8560: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
8570: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
8580: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8590: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
85a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
85b0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
85c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
85d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
85e0: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
85f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
8600: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
8610: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
8620: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
8630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
8640: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
8650: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
8660: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
8670: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
8680: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
8690: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
86a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
86b0: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
86c0: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
86d0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
86e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
86f0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
8700: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
8710: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
8720: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
8730: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
8740: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
8750: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
8760: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
8770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8780: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
8790: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
87a0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
87b0: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
87c0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
87d0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
87e0: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
87f0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
8800: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
8810: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
8820: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
8830: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
8840: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
8850: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8860: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
8870: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
8880: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
8890: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
88a0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
88b0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
88c0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
88d0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
88e0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
88f0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
8900: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
8910: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
8920: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
8930: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
8940: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
8950: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
8960: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
8970: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
8980: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
8990: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
89a0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
89b0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
89c0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
89d0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
89e0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
89f0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
8a00: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
8a10: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
8a20: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
8a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
8a40: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
8a50: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
8a60: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
8a70: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
8a80: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
8a90: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
8aa0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
8ab0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
8ac0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
8ad0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
8ae0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
8af0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
8b00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
8b10: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
8b20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
8b30: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
8b40: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
8b50: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
8b60: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
8b70: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
8b80: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
8b90: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
8ba0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
8bb0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
8bc0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
8bd0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
8be0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
8bf0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
8c00: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
8c10: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
8c20: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
8c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
8c40: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
8c50: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
8c60: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
8c70: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
8c80: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
8c90: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
8ca0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
8cb0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
8cc0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
8cd0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
8ce0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
8cf0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
8d00: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
8d10: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
8d20: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
8d30: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
8d40: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
8d50: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
8d60: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
8d70: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
8d80: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
8d90: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
8da0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  dules..**.** ^SQ
8db0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
8dc0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
8dd0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8de0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
8df0: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
8e00: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
8e10: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
8e20: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
8e30: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
8e40: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
8e50: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
8e60: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
8e70: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
8e80: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
8e90: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
8ea0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
8eb0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
8ec0: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70  e than.** 10 alp
8ed0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
8ee0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
8ef0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
8f00: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8f10: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8f20: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
8f30: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
8f40: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
8f50: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
8f60: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
8f70: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
8f80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8f90: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8fa0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8fb0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8fc0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8fd0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8fe0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8ff0: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
9000: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
9010: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
9020: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
9030: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
9040: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
9050: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
9060: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
9070: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
9080: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
9090: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
90a0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
90b0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
90c0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
90d0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
90e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
90f0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
9100: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
9110: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
9120: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
9130: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
9140: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
9150: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
9160: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
9170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9180: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
9190: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
91a0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
91b0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
91c0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
91d0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
91e0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
91f0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
9200: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
9210: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
9220: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
9230: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
9240: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
9250: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
9260: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
9270: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
9280: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
9290: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
92a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
92b0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
92c0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
92d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
92e0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
92f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9300: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9310: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
9320: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9330: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
9340: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9350: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
9360: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9370: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
9380: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9390: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
93a0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
93b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
93c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
93d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
93e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
93f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9400: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
9410: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
9420: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
9430: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
9440: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
9450: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
9460: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
9470: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
9480: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
9490: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
94a0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
94b0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
94c0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
94d0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
94e0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
94f0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
9500: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
9510: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
9520: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
9530: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
9540: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
9550: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
9560: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
9570: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
9580: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
9590: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
95a0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
95b0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
95c0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
95d0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
95e0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
95f0: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
9600: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
9610: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
9620: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
9630: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
9640: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
9650: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
9660: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
9670: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
9680: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9690: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
96a0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
96b0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
96c0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
96d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
96e0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
96f0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
9700: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
9710: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
9720: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
9730: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
9740: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
9750: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
9760: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
9770: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
9780: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
9790: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
97a0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
97b0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
97c0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
97d0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
97e0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
97f0: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
9800: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
9810: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
9820: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
9830: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
9840: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
9850: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
9860: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
9870: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
9880: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
9890: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
98a0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
98b0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
98c0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
98d0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
98e0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
98f0: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
9900: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
9910: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
9920: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
9930: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
9940: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
9950: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
9960: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
9970: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
9980: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
9990: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
99a0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
99b0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
99c0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
99d0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
99e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
99f0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
9a00: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
9a10: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
9a20: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
9a30: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
9a40: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
9a50: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
9a60: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
9a70: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
9a80: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
9a90: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
9aa0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
9ab0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
9ac0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
9ad0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
9ae0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
9af0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
9b00: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
9b10: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
9b20: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
9b30: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
9b40: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9b50: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
9b60: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
9b70: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
9b80: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
9b90: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
9ba0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
9bb0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
9bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  **.** ^The flags
9bd0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
9be0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
9bf0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9c00: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
9c10: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
9c20: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
9c30: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
9c40: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
9c50: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
9c60: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
9c70: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
9c80: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
9c90: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
9ca0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9cb0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
9cc0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
9cd0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
9ce0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
9cf0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
9d00: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
9d10: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
9d20: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
9d30: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
9d40: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
9d50: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
9d60: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
9d70: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
9d80: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
9d90: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
9da0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
9db0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9dc0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
9dd0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
9de0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
9df0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
9e00: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
9e10: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
9e20: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
9e30: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
9e40: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
9e50: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
9e60: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
9e70: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
9e80: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
9e90: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
9ea0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
9eb0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
9ec0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
9ed0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
9ee0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
9ef0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
9f00: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
9f10: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
9f20: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
9f30: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
9f40: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
9f50: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
9f60: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9f70: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
9f80: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
9f90: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
9fa0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
9fb0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
9fc0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
9fd0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
9fe0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
9ff0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
a000: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
a010: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
a020: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
a030: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
a040: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
a050: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
a060: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
a070: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
a080: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
a090: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
a0a0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
a0b0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
a0c0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
a0d0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
a0e0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
a0f0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
a100: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
a110: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
a120: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
a130: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
a140: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65   Number multiple
a150: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
a160: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
a170: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
a180: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
a190: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
a1a0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
a1b0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
a1c0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
a1d0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
a1e0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
a1f0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
a200: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
a210: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
a220: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
a230: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
a240: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
a250: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
a260: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
a270: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
a280: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
a290: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
a2a0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
a2b0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
a2c0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
a2d0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
a2e0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
a2f0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
a300: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
a310: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
a320: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
a330: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
a340: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
a350: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
a360: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
a370: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
a380: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
a390: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
a3a0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
a3b0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
a3c0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
a3d0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
a3e0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
a3f0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
a400: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
a410: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
a420: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
a430: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
a440: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
a450: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
a460: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
a470: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
a480: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
a490: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
a4a0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
a4b0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
a4c0: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
a4d0: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
a4e0: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
a4f0: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
a500: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
a510: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
a520: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
a530: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
a540: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
a550: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
a560: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
a570: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
a580: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
a590: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
a5a0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
a5b0: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
a5c0: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
a5d0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
a5e0: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
a5f0: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
a600: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
a610: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
a620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
a630: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
a640: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
a650: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
a660: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
a670: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
a680: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
a690: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
a6a0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
a6b0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
a6c0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
a6d0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
a6e0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
a6f0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
a700: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
a710: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
a720: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
a730: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
a740: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
a750: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
a760: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
a770: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
a780: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
a790: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
a7a0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
a7b0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
a7c0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
a7d0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
a7e0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
a7f0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
a800: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
a810: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
a820: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
a830: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a840: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
a850: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
a860: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
a870: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
a880: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
a890: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
a8a0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
a8b0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
a8c0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
a8d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a8e0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
a8f0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
a900: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
a910: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a920: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
a930: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
a940: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
a950: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
a960: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
a970: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
a980: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
a990: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
a9a0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
a9b0: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
a9c0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
a9d0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
a9e0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
a9f0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
aa00: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
aa10: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
aa20: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
aa30: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
aa40: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
aa50: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
aa60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
aa70: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
aa80: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
aa90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
aaa0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
aab0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
aac0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
aad0: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
aae0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
aaf0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
ab00: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
ab10: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
ab20: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
ab30: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
ab40: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
ab50: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
ab60: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
ab70: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
ab80: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ab90: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
aba0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
abb0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
abc0: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
abd0: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
abe0: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
abf0: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ac00: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ac10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ac20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ac30: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ac40: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
ac50: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
ac60: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
ac70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ac80: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ac90: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
aca0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
acb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
acc0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
acd0: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
ace0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
acf0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
ad00: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
ad10: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ad20: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
ad30: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
ad40: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
ad50: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
ad60: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
ad70: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
ad80: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
ad90: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
ada0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
adb0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
adc0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
add0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ade0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
adf0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
ae00: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
ae10: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
ae20: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
ae30: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
ae40: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
ae50: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
ae60: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
ae70: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
ae80: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
ae90: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
aea0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
aeb0: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
aec0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
aed0: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
aee0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
aef0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
af00: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
af10: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
af20: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
af30: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
af40: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
af50: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
af60: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
af70: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
af80: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
af90: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
afa0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
afb0: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
afc0: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
afd0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
afe0: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
aff0: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
b000: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
b010: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
b020: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
b030: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
b040: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
b050: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
b060: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
b070: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b080: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
b090: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
b0a0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
b0b0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
b0c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
b0d0: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
b0e0: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
b0f0: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
b100: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
b110: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
b120: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
b130: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
b140: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
b150: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
b160: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b170: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
b180: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
b190: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
b1a0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
b1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b1c0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
b1d0: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
b1e0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
b1f0: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
b200: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
b210: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
b220: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
b230: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
b240: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
b250: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
b260: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
b270: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
b280: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
b290: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
b2a0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
b2b0: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
b2c0: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
b2d0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
b2e0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
b2f0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
b300: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b310: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
b320: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b330: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
b340: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
b350: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
b360: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
b370: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
b380: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
b390: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
b3a0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
b3b0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
b3c0: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
b3d0: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
b3e0: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
b3f0: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
b400: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
b410: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
b420: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
b430: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b440: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
b450: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
b460: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
b470: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
b480: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
b490: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
b4a0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
b4b0: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
b4c0: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
b4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
b4e0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
b4f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
b500: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
b510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b520: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
b530: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b540: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
b550: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
b560: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
b570: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
b580: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
b590: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
b5a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
b5b0: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
b5c0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
b5d0: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
b5e0: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
b5f0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
b600: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
b610: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
b620: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
b630: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
b640: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
b650: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
b660: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
b670: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
b680: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
b690: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
b6a0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
b6b0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
b6c0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
b6d0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
b6e0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
b6f0: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
b700: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
b710: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
b720: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
b730: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
b740: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
b750: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
b760: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
b770: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
b780: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
b790: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b7a0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
b7b0: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
b7c0: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
b7d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
b7e0: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
b7f0: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
b800: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
b810: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
b820: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
b830: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b850: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
b860: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
b870: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
b880: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b890: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
b8a0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
b8b0: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
b8c0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
b8d0: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
b8e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b8f0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
b900: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
b910: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b920: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
b930: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
b940: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
b950: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b960: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
b970: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
b980: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
b990: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
b9a0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
b9b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
b9c0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
b9d0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
b9e0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
b9f0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
ba00: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ba10: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
ba20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ba30: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
ba40: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
ba50: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ba60: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
ba70: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
ba80: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
ba90: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
baa0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bab0: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
bac0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
bad0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
bae0: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
baf0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
bb00: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
bb10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
bb20: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
bb30: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
bb40: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
bb50: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
bb60: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
bb70: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
bb80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bb90: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
bba0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
bbb0: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
bbc0: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
bbd0: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
bbe0: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
bbf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
bc00: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
bc10: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
bc20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bc30: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
bc40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bc50: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
bc60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bc70: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
bc80: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
bc90: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
bca0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bcb0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
bcc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
bcd0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
bce0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
bcf0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
bd00: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
bd10: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
bd20: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
bd30: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
bd40: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
bd50: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
bd60: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
bd70: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
bd80: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
bd90: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
bda0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
bdb0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
bdc0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
bdd0: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
bde0: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
bdf0: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
be00: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
be10: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
be20: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
be30: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
be40: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
be50: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
be60: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
be70: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
be80: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
be90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bea0: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
beb0: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
bec0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
bed0: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
bee0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
bef0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
bf00: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
bf10: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
bf20: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
bf30: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
bf40: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
bf50: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
bf60: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
bf70: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
bf80: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
bf90: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
bfa0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
bfb0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
bfc0: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
bfd0: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
bfe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bff0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
c000: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
c010: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
c020: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
c030: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
c040: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
c050: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
c060: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
c070: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
c080: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
c090: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
c0a0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
c0b0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
c0c0: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
c0d0: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
c0e0: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
c0f0: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
c100: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
c110: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
c120: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
c130: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
c140: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
c150: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
c160: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
c170: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
c180: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
c190: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
c1a0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
c1b0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
c1c0: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
c1d0: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
c1e0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
c1f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c200: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
c210: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
c220: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
c230: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
c240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
c250: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
c260: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
c270: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
c280: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
c290: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
c2a0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
c2b0: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
c2c0: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
c2d0: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
c2e0: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
c2f0: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
c300: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
c310: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
c320: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
c330: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
c340: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
c350: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c360: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
c370: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
c380: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
c390: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
c3a0: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
c3b0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c3c0: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
c3d0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
c3e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
c3f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c400: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
c410: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
c420: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
c430: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
c440: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
c450: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
c460: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
c470: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
c480: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
c490: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c4b0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
c4c0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
c4d0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
c4e0: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
c4f0: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
c500: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
c510: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
c520: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
c530: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
c540: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
c550: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
c560: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
c570: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
c580: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
c590: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
c5a0: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
c5b0: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
c5c0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
c5d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c5e0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
c5f0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
c600: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
c610: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c620: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
c630: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
c640: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
c650: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
c660: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
c670: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
c680: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
c690: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
c6a0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
c6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c6c0: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
c6d0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
c6e0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
c6f0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
c700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c710: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
c720: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
c730: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
c740: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
c750: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
c760: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
c770: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
c780: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c790: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c7a0: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
c7b0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
c7c0: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
c7d0: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
c7e0: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
c7f0: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
c800: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
c810: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
c820: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
c830: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
c840: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
c850: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
c860: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
c870: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
c880: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
c890: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
c8a0: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
c8b0: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
c8c0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
c8d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
c8e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
c8f0: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
c900: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
c910: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
c920: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
c930: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
c940: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
c950: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
c960: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
c970: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
c980: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
c990: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
c9a0: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
c9b0: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
c9c0: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
c9d0: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
c9e0: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
c9f0: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
ca00: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
ca10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ca20: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
ca30: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
ca40: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
ca50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
ca60: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
ca70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ca80: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
ca90: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
caa0: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
cab0: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
cac0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
cad0: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
cae0: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
caf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
cb00: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
cb10: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
cb20: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
cb30: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
cb40: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
cb50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
cb60: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
cb70: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cb80: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
cb90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
cba0: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
cbb0: 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
cbc0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
cbd0: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
cbe0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
cbf0: 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
cc00: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
cc10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
cc20: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
cc30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cc40: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
cc50: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
cc60: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
cc70: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
cc80: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
cc90: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
cca0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
ccb0: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
ccc0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
ccd0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
cce0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
ccf0: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
cd00: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
cd10: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
cd20: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
cd30: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
cd40: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
cd50: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
cd60: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
cd70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cd80: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
cd90: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
cda0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
cdb0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
cdc0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
cdd0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
cde0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
cdf0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
ce00: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
ce10: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ce20: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
ce30: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
ce40: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
ce50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ce60: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
ce70: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ce80: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
ce90: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
cea0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
ceb0: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
cec0: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
ced0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
cee0: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
cef0: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
cf00: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
cf10: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
cf20: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
cf30: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
cf40: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
cf50: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
cf60: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
cf70: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
cf80: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
cf90: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
cfa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
cfb0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
cfc0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
cfd0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
cfe0: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
cff0: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
d000: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
d010: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
d020: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d030: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
d040: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
d050: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
d060: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
d070: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
d080: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d090: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
d0a0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d0b0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
d0c0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
d0d0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
d0e0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
d0f0: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
d100: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
d110: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
d120: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
d130: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d140: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
d150: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
d160: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
d170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d180: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
d190: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d1a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
d1b0: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
d1c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d1d0: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
d1e0: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
d1f0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d200: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
d210: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
d220: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
d230: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d240: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
d250: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
d260: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
d270: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
d280: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
d290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
d2a0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
d2b0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
d2c0: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
d2d0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
d2e0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
d2f0: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
d300: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
d310: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
d320: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
d330: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
d340: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
d350: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
d360: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d370: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
d380: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
d390: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
d3a0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
d3b0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
d3c0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
d3d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d3e0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
d3f0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
d400: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
d410: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
d420: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
d430: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
d440: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
d450: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
d460: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
d470: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
d480: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
d490: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
d4a0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
d4b0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
d4c0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
d4d0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
d4e0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e  * The xMalloc an
d4f0: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
d500: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
d510: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61  he.** malloc() a
d520: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
d530: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
d540: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
d550: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63  .** The xRealloc
d560: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72   method must wor
d570: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29  k like realloc()
d580: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
d590: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20  rd C library.** 
d5a0: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69  with the excepti
d5b0: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73  on that if the s
d5c0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d5d0: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65  o xRealloc is ze
d5e0: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  ro,.** xRealloc 
d5f0: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20  must be a no-op 
d600: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65  - it must not pe
d610: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61  rform any alloca
d620: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c  tion or.** deall
d630: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74  ocation.  ^SQLit
d640: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d650: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
d660: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
d670: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
d680: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d690: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
d6a0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20  to xRoundup..** 
d6b0: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20  And so in cases 
d6c0: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61  where xRoundup a
d6d0: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
d6e0: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c  positive number,
d6f0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e  .** xRealloc can
d700: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79   perform exactly
d710: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64   as the standard
d720: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63   library realloc
d730: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20  () and.** still 
d740: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65  be in compliance
d750: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69   with this speci
d760: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  fication..**.** 
d770: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
d780: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
d790: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
d7a0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
d7b0: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
d7c0: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
d7d0: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
d7e0: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
d7f0: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
d800: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
d810: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
d820: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
d830: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
d840: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
d850: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
d860: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
d870: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
d880: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
d890: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
d8a0: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
d8b0: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
d8c0: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
d8d0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
d8e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
d8f0: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
d900: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
d910: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
d920: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
d930: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
d940: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
d950: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
d960: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
d970: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
d980: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
d990: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
d9a0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
d9b0: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
d9c0: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
d9d0: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
d9e0: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
d9f0: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
da00: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
da10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
da20: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
da30: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
da40: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
da50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
da60: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
da70: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
da80: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
da90: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
daa0: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
dab0: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
dac0: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
dad0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
dae0: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
daf0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
db00: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
db10: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
db20: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
db30: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
db40: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
db50: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
db60: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
db70: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
db80: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
db90: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
dba0: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
dbb0: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
dbc0: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
dbd0: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
dbe0: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
dbf0: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
dc00: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
dc10: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
dc20: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
dc30: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
dc40: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
dc50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dc60: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
dc70: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
dc80: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
dc90: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
dca0: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
dcb0: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
dcc0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
dcd0: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
dce0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
dcf0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dd00: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
dd10: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
dd20: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
dd30: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
dd40: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
dd50: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
dd60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
dd70: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
dd80: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
dd90: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dda0: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
ddb0: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
ddc0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
ddd0: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
dde0: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
ddf0: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
de00: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
de10: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
de20: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
de30: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
de40: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
de50: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
de60: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
de70: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
de80: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
de90: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
dea0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
deb0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
dec0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ded0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
dee0: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
def0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
df00: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
df10: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
df20: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
df30: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
df40: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
df50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
df60: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
df70: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
df80: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
df90: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
dfa0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
dfb0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
dfc0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
dfd0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
dfe0: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
dff0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
e000: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
e010: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
e020: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
e030: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
e040: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
e050: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
e060: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
e070: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
e080: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
e090: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
e0a0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
e0b0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
e0c0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
e0d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
e0e0: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
e0f0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
e100: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
e110: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
e120: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
e130: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
e140: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
e150: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
e160: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e170: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
e180: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
e190: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
e1a0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
e1b0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
e1c0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
e1d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e1e0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
e1f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
e200: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
e210: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
e220: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
e230: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
e240: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
e250: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
e260: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
e270: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
e280: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
e290: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
e2a0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
e2b0: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
e2c0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
e2d0: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
e2e0: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
e2f0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
e300: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
e310: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
e320: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e330: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
e340: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
e350: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e360: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
e370: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
e380: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
e390: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
e3a0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
e3b0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
e3c0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
e3d0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
e3e0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e3f0: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
e400: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
e410: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
e420: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
e430: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
e440: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
e450: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
e460: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e470: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e480: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e490: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e4a0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e4b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e4c0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e4d0: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
e4e0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
e4f0: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
e500: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
e510: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
e520: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
e530: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e540: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
e550: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
e560: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
e570: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e580: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
e590: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e5a0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e5b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e5c0: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
e5d0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
e5e0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
e5f0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
e600: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
e610: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
e620: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
e630: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e640: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e650: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
e660: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
e670: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
e680: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e690: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
e6a0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e6b0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
e6c0: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
e6d0: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
e6e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e6f0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e700: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
e710: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
e720: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
e730: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
e740: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
e750: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
e760: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
e770: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
e780: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
e790: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
e7a0: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
e7b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e7c0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
e7d0: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
e7e0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e7f0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e800: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e810: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e820: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e830: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e840: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e850: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
e860: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
e870: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
e880: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e890: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
e8a0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
e8b0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
e8c0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
e8d0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
e8e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e8f0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
e900: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e910: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
e920: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
e930: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
e940: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
e950: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
e960: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
e970: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
e980: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
e990: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
e9a0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
e9b0: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
e9c0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
e9d0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
e9e0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
e9f0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
ea00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
ea10: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
ea20: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
ea30: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
ea40: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ea50: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
ea60: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
ea70: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
ea80: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
ea90: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
eaa0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
eab0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eac0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
ead0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
eae0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
eaf0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
eb00: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
eb10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eb20: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
eb30: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
eb40: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
eb50: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
eb60: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
eb70: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
eb80: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
eb90: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
eba0: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
ebb0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
ebc0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ebd0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
ebe0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
ebf0: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
ec00: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
ec10: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
ec20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ec30: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
ec40: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
ec50: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
ec60: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
ec70: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
ec80: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ec90: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eca0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ecb0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
ecc0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ecd0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ece0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ecf0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ed00: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
ed10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
ed20: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
ed30: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
ed40: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
ed50: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
ed60: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ed70: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ed80: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
ed90: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
eda0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
edb0: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
edc0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
edd0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
ede0: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
edf0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
ee00: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
ee10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ee20: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
ee30: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
ee40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
ee50: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
ee60: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ee70: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
ee80: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
ee90: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
eea0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
eeb0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
eec0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
eed0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
eee0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
eef0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
ef00: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ef10: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
ef20: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
ef30: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ef40: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
ef50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ef60: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
ef70: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
ef80: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
ef90: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
efa0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
efb0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
efc0: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
efd0: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
efe0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
eff0: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
f000: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
f010: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
f020: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f030: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f040: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
f050: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
f060: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
f070: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
f080: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
f090: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
f0a0: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
f0b0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f0c0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
f0d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f0e0: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
f0f0: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
f100: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f110: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
f120: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
f130: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
f140: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
f150: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
f160: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
f170: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
f180: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
f190: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
f1a0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
f1b0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f1c0: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
f1d0: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
f1e0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
f1f0: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
f200: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
f210: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f220: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
f230: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
f240: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
f250: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f260: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
f270: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
f280: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
f290: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
f2a0: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
f2b0: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
f2c0: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
f2d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f2e0: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
f2f0: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f300: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f310: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f320: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f330: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f340: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
f350: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
f360: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
f370: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
f380: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
f390: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
f3a0: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
f3b0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
f3c0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
f3d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
f3e0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
f3f0: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
f400: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
f410: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
f420: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
f430: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
f440: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
f450: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
f460: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f470: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
f480: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
f490: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
f4a0: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
f4b0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
f4c0: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
f4d0: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
f4e0: 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
f4f0: 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
f500: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
f510: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
f520: 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
f530: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
f540: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
f550: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f560: 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
f570: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
f580: 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
f590: 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
f5a0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
f5b0: 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
f5c0: 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
f5d0: 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
f5e0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
f5f0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
f600: 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
f610: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
f620: 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
f630: 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
f640: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
f650: 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
f660: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f670: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f680: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
f690: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f6a0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f6b0: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f6c0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f6d0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f6e0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
f6f0: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
f700: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
f710: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69  ache implemenati
f720: 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
f730: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
f740: 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
f750: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
f760: 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
f770: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
f780: 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
f790: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
f7a0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70  CONFIG_PCACHE op
f7b0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
f7c0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
f7d0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
f7e0: 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
f7f0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
f800: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
f810: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
f820: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
f830: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
f840: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
f850: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
f860: 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
f870: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
f880: 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
f890: 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
f8a0: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
f8b0: 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
f8c0: 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
f8d0: 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
f8e0: 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
f8f0: 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
f900: 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
f910: 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
f920: 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
f930: 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
f940: 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
f950: 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
f960: 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
f970: 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
f980: 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
f990: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
f9a0: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
f9b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
f9c0: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
f9d0: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
f9e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f9f0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
fa00: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
fa10: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
fa20: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
fa30: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
fa40: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
fa50: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
fa60: 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
fa70: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
fa80: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
fa90: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
faa0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
fab0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
fac0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
fad0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
fae0: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
faf0: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
fb00: 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
fb10: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
fb20: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
fb30: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
fb40: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
fb50: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
fb60: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
fb70: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
fb80: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
fb90: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fba0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
fbb0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
fbc0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
fbd0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
fbe0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
fbf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
fc00: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
fc10: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
fc20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
fc30: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
fc40: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
fc50: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
fc60: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
fc70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
fc80: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
fc90: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
fca0: 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
fcb0: 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
fcc0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
fcd0: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
fce0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
fcf0: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
fd00: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
fd10: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
fd20: 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
fd30: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
fd40: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
fd50: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
fd60: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
fd70: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
fd80: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
fd90: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
fda0: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
fdb0: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
fdc0: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
fdd0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
fde0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
fdf0: 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
fe00: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
fe10: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
fe20: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
fe30: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
fe40: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
fe50: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
fe60: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
fe70: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
fe80: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
fe90: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
fea0: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
feb0: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
fec0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
fed0: 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
fee0: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
fef0: 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
ff00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
ff10: 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
ff20: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
ff30: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
ff40: 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
ff50: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
ff60: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
ff70: 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
ff80: 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62  t 2^12. Reasonab
ff90: 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
ffa0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
ffb0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
ffc0: 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38   2^5 through 2^8
ffd0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ffe0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
fff0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
10000 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10010 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10020 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10030 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10040 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
10050 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
10060 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
10070 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
10080 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
10090 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
100a0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
100b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
100c0 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
100d0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
100e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
100f0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
10100 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10110 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
10120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
10130 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
10140 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
10150 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
10160 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10170 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
10180 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10190 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
101a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
101b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
101c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
101d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
101e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
101f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10200 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10210 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10220 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10230 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10240 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
10250 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
10260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10270 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
10280 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10290 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
102a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
102b0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
102c0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
102d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
102e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
102f0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10300 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
10310 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
10320 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
10330 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
10340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
10350 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
10360 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
10370 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
10380 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
10390 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
103a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
103b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
103c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
103d0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
103e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
103f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
10400 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
10410 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
10420 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
10430 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
10440 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
10450 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10460 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
10470 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10480 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10490 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
104a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
104b0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
104c0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
104d0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
104e0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
104f0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
10500 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
10510 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
10520 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
10530 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
10540 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10550 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
10560 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
10570 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10590 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
105a0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
105b0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
105c0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
105d0 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
105e0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
105f0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
10600 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10610 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
10620 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10630 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
10640 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
10650 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
10660 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
10670 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
10680 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
10690 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
106a0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
106b0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
106c0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
106d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
106e0 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
106f0 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
10700 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
10710 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
10720 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
10730 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
10740 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
10750 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
10760 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
10770 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
10780 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
10790 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
107a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
107b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
107c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
107d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
107e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
107f0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10800 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
10810 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10820 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
10830 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
10840 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
10850 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
10860 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
10870 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
10880 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
10890 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
108a0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
108b0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
108c0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
108d0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
108e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
108f0 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74  IG_GETPCACHE</dt
10900 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
10910 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
10920 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10930 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
10940 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
10950 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
10960 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
10970 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
10980 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
10990 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
109a0 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
109b0 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
109c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
109d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
109e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
109f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10a00 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
10a10 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
10a20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
10a30 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
10a40 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
10a50 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
10a60 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
10a70 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
10a80 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
10a90 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
10aa0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
10ab0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
10ac0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
10ad0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
10ae0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
10af0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
10b00 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
10b10 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
10b20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10b30 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
10b40 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
10b50 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
10b60 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
10b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
10b80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
10b90 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
10ba0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
10bb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
10bc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10bd0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
10be0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
10bf0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
10c00 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
10c10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
10c20 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
10c30 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
10c40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
10c50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
10c60 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
10c70 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
10c80 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
10c90 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
10ca0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
10cb0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
10cc0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
10cd0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
10ce0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
10cf0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
10d00 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
10d10 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
10d20 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
10d30 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
10d40 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
10d50 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
10d60 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
10d70 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
10d80 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
10d90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10da0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
10db0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
10dc0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
10dd0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
10de0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
10df0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10e00 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
10e10 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
10e20 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
10e30 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10e50 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10e60 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
10e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10e80 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
10e90 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
10ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10eb0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10ec0 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
10ed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10ee0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
10ef0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
10f00 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
10f10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10f20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10f30 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
10f40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10f50 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
10f70 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
10f80 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
10f90 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
10fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10fb0 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
10fc0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10fd0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10fe0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10ff0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
11000 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
11010 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
11020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11030 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11040 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
11050 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
11060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11070 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
11080 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11090 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
110a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
110b0 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
110c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
110d0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
110e0 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
110f0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
11100 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
11110 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
11120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11130 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11140 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
11150 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
11160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11170 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
11180 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11190 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
111a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
111b0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
111c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
111d0 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
111e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
111f0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
11200 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
11210 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
11220 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
11230 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
11240 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11250 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
11260 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
11270 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11280 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11290 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
112a0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
112b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
112c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
112d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
112e0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
112f0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11300 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11310 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
11320 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
11330 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11340 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11350 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11360 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11370 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11380 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11390 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
113a0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
113b0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
113c0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
113d0 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
113e0 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
113f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
11400 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
11410 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
11420 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
11430 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
11440 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
11450 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11460 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
11470 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
11480 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
11490 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
114a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
114b0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
114c0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
114d0 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
114e0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
114f0 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
11500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
11510 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
11520 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
11530 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
11540 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
11550 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
11560 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11570 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11580 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
11590 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
115a0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
115b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
115c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
115d0 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
115e0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
115f0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
11600 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
11610 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
11620 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
11630 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
11640 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
11650 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
11660 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
11670 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11680 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11690 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
116a0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
116b0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
116c0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
116d0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
116e0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
116f0 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
11700 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11710 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
11720 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
11730 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
11740 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
11750 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
11760 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
11770 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
11780 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
11790 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
117a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
117b0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
117c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
117d0 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
117e0 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
117f0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
11800 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
11810 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
11820 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
11830 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
11840 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
11850 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
11860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
11870 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
11880 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
11890 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
118a0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
118b0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
118c0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
118d0 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
118e0 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
118f0 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
11900 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
11910 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
11920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
11930 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
11940 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
11950 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
11960 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
11970 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
11980 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
11990 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
119a0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
119b0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
119c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
119d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
119e0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
119f0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
11a00 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
11a10 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11a20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
11a30 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
11a40 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
11a50 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
11a60 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
11a70 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
11a80 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
11a90 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
11aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
11ab0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
11ac0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
11ad0 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
11ae0 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
11af0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
11b00 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
11b10 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
11b20 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
11b30 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
11b40 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
11b50 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
11b60 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
11b70 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
11b80 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
11b90 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
11ba0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
11bb0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
11bc0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
11bd0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
11be0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11bf0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
11c00 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
11c10 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
11c20 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
11c30 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
11c40 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
11c50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
11c60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
11c70 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
11c80 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11c90 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
11ca0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
11cb0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
11cc0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
11cd0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
11ce0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
11cf0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
11d00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
11d10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
11d20 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
11d30 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
11d40 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
11d50 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
11d60 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
11d70 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
11d80 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
11d90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11da0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11db0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
11dc0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
11dd0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
11de0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
11df0 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
11e00 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
11e10 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
11e20 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
11e30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
11e40 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
11e50 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
11e60 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
11e70 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
11e80 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
11e90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
11ea0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
11eb0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11ec0 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
11ed0 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
11ee0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
11ef0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
11f00 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
11f10 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
11f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11f30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
11f40 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
11f50 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
11f60 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
11f70 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
11f80 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
11f90 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
11fa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
11fb0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11fc0 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
11fd0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
11fe0 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
11ff0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
12000 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
12010 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
12020 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
12030 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
12040 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
12050 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
12060 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
12070 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
12080 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
12090 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
120a0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
120b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
120c0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
120d0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
120e0 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
120f0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
12100 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
12110 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
12120 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
12130 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
12140 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
12150 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
12160 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
12170 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
12180 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
12190 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
121a0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
121b0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
121c0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
121d0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
121e0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
121f0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
12200 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
12210 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
12220 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
12230 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
12240 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
12250 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
12260 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
12270 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
12280 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
12290 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
122a0 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
122b0 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
122c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
122d0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
122e0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
122f0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
12300 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
12310 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
12320 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
12330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
12340 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
12350 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
12360 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
12370 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
12380 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
12390 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
123a0 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
123b0 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
123c0 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
123d0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
123e0 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
123f0 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
12400 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
12410 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12420 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
12430 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
12440 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
12450 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
12460 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
12470 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
12480 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
12490 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
124a0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
124b0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
124c0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
124d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
124e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
124f0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
12500 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
12510 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
12520 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
12530 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
12540 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
12550 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
12560 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
12570 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
12580 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
12590 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
125a0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
125b0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
125c0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
125d0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
125e0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
125f0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
12600 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
12610 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
12620 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
12630 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
12640 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
12650 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
12660 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
12670 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
12680 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
12690 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
126a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
126b0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
126c0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
126d0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
126e0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
126f0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
12700 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
12710 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
12720 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
12730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
12740 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
12750 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
12760 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
12770 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
12780 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
12790 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
127a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
127b0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
127c0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
127d0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
127e0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
127f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
12800 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
12810 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
12820 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
12830 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
12840 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12850 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
12860 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12870 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
12880 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
12890 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
128a0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
128b0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
128c0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
128d0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
128e0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
128f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
12900 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
12910 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
12920 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
12930 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
12940 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
12950 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
12960 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12970 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12980 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
12990 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
129a0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
129b0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
129c0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
129d0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
129e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
129f0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
12a00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
12a10 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
12a20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12a30 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
12a40 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
12a50 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
12a60 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
12a70 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
12a80 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
12a90 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
12aa0 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
12ab0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
12ac0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
12ad0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
12ae0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
12af0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
12b00 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
12b10 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
12b20 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
12b30 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
12b40 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
12b50 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
12b60 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
12b70 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
12b80 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
12b90 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
12ba0 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
12bb0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
12bc0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
12bd0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
12be0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
12bf0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
12c00 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
12c10 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
12c20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
12c30 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
12c40 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
12c50 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
12c60 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
12c70 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
12c80 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
12c90 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
12ca0 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
12cb0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
12cc0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
12cd0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
12ce0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
12cf0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
12d00 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
12d10 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
12d20 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
12d30 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
12d40 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
12d50 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
12d60 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
12d70 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
12d80 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
12d90 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
12da0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
12db0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
12dc0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
12dd0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
12de0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
12df0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
12e00 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
12e10 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
12e20 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
12e30 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
12e40 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
12e50 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
12e60 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
12e70 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
12e80 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
12e90 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
12ea0 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
12eb0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
12ec0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
12ed0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
12ee0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
12ef0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12f00 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
12f10 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
12f20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
12f30 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
12f40 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12f50 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
12f60 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
12f70 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
12f80 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
12f90 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
12fa0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
12fb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
12fc0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
12fd0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
12fe0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
12ff0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
13000 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
13010 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
13020 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
13030 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
13040 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
13050 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
13060 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
13070 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
13080 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
13090 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
130a0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
130b0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
130c0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
130d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
130e0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
130f0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
13100 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
13110 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
13120 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
13130 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
13140 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
13150 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
13160 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
13170 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
13180 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
13190 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
131a0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
131b0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
131c0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
131d0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
131e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
131f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
13200 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
13210 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
13220 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
13230 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
13240 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
13250 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
13260 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
13270 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
13280 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
13290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
132a0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
132b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
132c0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
132d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
132e0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
132f0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
13300 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
13310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13320 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
13330 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
13340 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
13350 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
13360 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
13370 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13380 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13390 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
133a0 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
133b0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
133c0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
133d0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
133e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133f0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
13400 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
13410 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
13420 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
13430 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
13440 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
13450 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
13460 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
13470 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
13480 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
13490 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
134a0 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
134b0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
134c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
134d0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
134e0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
134f0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
13500 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
13510 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
13520 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
13530 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
13540 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
13550 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
13560 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
13570 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
13580 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
13590 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
135a0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
135b0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
135c0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
135d0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
135e0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
135f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
13600 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
13610 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
13620 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
13630 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
13640 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
13650 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
13660 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
13670 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
13680 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
13690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
136a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
136b0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
136c0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
136d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
136e0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
136f0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
13700 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
13710 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
13720 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
13730 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
13740 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
13750 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
13760 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
13770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
13780 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
13790 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
137a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
137b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
137c0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
137d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
137e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
137f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13800 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
13810 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
13820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
13830 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
13840 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
13850 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
13860 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
13870 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
13880 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
13890 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
138a0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
138b0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
138c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
138d0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
138e0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
138f0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
13900 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
13910 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
13920 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
13930 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
13940 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
13950 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
13960 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
13970 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
13980 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
13990 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
139a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
139b0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
139c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
139d0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
139e0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
139f0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
13a00 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
13a10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
13a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13a30 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
13a40 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
13a50 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
13a60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
13a70 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
13a80 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
13a90 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
13aa0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
13ab0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
13ac0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
13ad0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
13ae0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
13af0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
13b00 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
13b10 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
13b20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
13b30 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
13b40 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
13b50 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
13b60 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
13b70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
13b80 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
13b90 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
13ba0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
13bb0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
13bc0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
13bd0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
13be0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
13bf0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
13c00 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
13c10 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
13c20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
13c30 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
13c40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
13c50 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
13c60 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
13c70 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
13c80 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
13c90 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
13ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13cb0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
13cc0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
13cd0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
13ce0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
13cf0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
13d00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
13d10 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
13d20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
13d30 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
13d40 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
13d50 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
13d60 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
13d70 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
13d80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13d90 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
13da0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
13db0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
13dc0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
13dd0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
13de0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
13df0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
13e00 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
13e10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
13e20 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
13e30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13e40 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
13e50 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
13e60 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
13e70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
13e80 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
13e90 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
13ea0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
13eb0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
13ec0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
13ed0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
13ee0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
13ef0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
13f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
13f10 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
13f20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
13f30 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
13f40 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
13f50 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
13f60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
13f70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
13f80 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
13f90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13fa0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13fb0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13fc0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
13fd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13fe0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
13ff0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
14000 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
14010 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
14020 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
14030 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
14040 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
14050 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
14060 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
14070 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
14080 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
14090 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
140a0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
140b0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
140c0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
140d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
140e0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
140f0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
14100 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
14110 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
14120 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
14130 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
14140 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
14150 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
14160 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
14170 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
14180 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
14190 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
141a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
141b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
141c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
141d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
141e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
141f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
14200 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
14210 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
14220 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
14230 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
14240 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
14250 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
14260 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
14270 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
14280 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
14290 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
142a0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
142b0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
142c0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
142d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
142e0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
142f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14300 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
14310 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
14320 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
14330 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
14340 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
14350 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
14360 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
14370 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
14380 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
14390 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
143a0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
143b0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
143c0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
143d0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
143e0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
143f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
14400 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
14410 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
14420 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
14430 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
14440 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
14450 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
14460 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
14470 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
14480 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
14490 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
144a0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
144b0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
144c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
144d0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
144e0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
144f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
14500 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
14510 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
14520 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
14530 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
14540 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
14550 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14560 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
14570 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
14580 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
14590 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
145a0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
145b0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
145c0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
145d0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
145e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
145f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
14600 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
14610 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
14620 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
14630 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
14640 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
14650 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
14660 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
14670 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
14680 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
14690 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
146a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
146b0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
146c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
146d0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
146e0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
146f0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
14700 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
14710 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
14720 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
14730 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
14740 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
14750 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
14760 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
14770 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14780 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
14790 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
147a0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
147b0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
147c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
147d0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
147e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
147f0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
14800 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
14810 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
14820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14830 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
14840 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
14850 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
14860 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
14870 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14880 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
14890 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
148a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
148b0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
148c0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
148d0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
148e0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
148f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
14900 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
14910 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
14920 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
14930 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
14940 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
14950 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
14960 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
14970 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
14980 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
14990 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
149a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
149b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
149c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
149d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
149e0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
149f0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
14a00 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
14a10 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
14a20 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
14a30 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
14a40 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
14a50 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
14a60 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
14a70 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
14a80 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
14a90 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
14aa0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
14ab0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
14ac0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
14ad0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
14ae0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
14af0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
14b00 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
14b10 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
14b20 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
14b30 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
14b40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14b50 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
14b60 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
14b70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
14b80 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
14b90 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
14ba0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
14bb0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
14bc0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
14bd0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
14be0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
14bf0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
14c00 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
14c10 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
14c20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
14c30 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
14c40 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
14c50 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
14c60 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
14c70 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
14c80 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
14c90 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
14ca0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
14cb0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
14cc0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
14cd0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
14ce0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
14cf0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
14d00 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
14d10 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
14d20 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
14d30 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
14d40 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
14d50 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
14d60 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
14d70 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
14d80 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
14d90 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
14da0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
14db0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
14dc0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
14dd0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
14de0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
14df0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
14e00 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
14e10 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
14e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
14e30 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
14e40 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
14e50 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14e60 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
14e70 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
14e80 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
14e90 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
14ea0 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
14eb0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
14ec0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
14ed0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
14ee0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
14ef0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
14f00 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
14f10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
14f20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
14f30 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
14f40 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
14f50 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
14f60 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
14f70 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
14f80 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
14f90 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
14fa0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
14fb0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
14fc0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
14fd0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
14fe0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
14ff0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
15000 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
15010 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
15020 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
15030 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
15040 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
15050 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
15060 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
15070 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
15080 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
15090 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
150a0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
150b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
150c0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
150d0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
150e0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
150f0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
15100 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
15110 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
15120 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
15130 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
15140 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
15150 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
15160 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
15170 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
15180 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
15190 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
151a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
151b0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
151c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
151d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
151e0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
151f0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
15200 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
15210 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
15220 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
15230 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
15240 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
15250 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
15260 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
15270 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
15280 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
15290 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
152a0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
152b0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
152c0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
152d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
152e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
152f0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
15300 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
15310 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
15320 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
15330 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
15340 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
15350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
15370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15380 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
15390 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
153a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
153b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
153c0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
153d0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
153e0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
153f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
15400 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
15410 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
15420 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
15430 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
15440 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
15450 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
15460 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
15470 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
15480 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
15490 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
154a0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
154b0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
154c0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
154d0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
154e0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
154f0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
15500 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
15510 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
15520 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
15530 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
15540 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
15550 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
15560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
15570 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
15580 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
15590 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
155a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
155b0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
155c0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
155d0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
155e0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
155f0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
15600 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
15610 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
15620 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
15630 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
15640 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
15650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15660 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
15670 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
15680 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
15690 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
156a0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
156b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
156c0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
156d0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
156e0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
156f0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
15700 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
15710 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
15720 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
15730 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
15740 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
15750 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
15760 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
15770 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
15780 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
15790 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
157a0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
157b0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
157c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
157d0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
157e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
157f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
15800 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
15810 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
15820 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
15830 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
15840 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
15850 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15860 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
15870 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
15880 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
15890 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
158a0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
158b0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
158c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
158d0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
158e0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
158f0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
15900 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
15910 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
15920 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
15930 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
15940 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
15950 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
15960 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
15970 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
15980 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
15990 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
159a0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
159b0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
159c0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
159d0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
159e0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
159f0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
15a00 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
15a10 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
15a20 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
15a30 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
15a40 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
15a50 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
15a60 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
15a70 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
15a80 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
15a90 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
15aa0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
15ab0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
15ac0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
15ad0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
15ae0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
15af0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
15b00 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
15b10 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
15b20 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
15b30 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
15b40 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
15b50 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
15b60 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
15b70 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
15b80 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
15b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
15ba0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
15bb0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
15bc0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
15bd0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
15be0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
15bf0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
15c00 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
15c10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15c20 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
15c30 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
15c40 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
15c50 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
15c60 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
15c70 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
15c80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
15c90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15ca0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
15cb0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
15cc0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
15cd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
15ce0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
15cf0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
15d00 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
15d10 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
15d20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
15d30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15d40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15d50 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
15d60 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
15d70 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
15d80 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
15d90 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
15da0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
15db0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
15dc0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
15dd0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
15de0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
15df0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
15e00 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
15e10 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15e20 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
15e30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
15e40 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
15e50 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15e60 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
15e70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15e80 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
15e90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15ea0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
15eb0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
15ec0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
15ed0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
15ee0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15ef0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
15f00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15f10 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
15f20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15f30 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
15f40 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15f50 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
15f60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
15f70 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
15f80 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
15f90 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
15fa0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
15fb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
15fc0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
15fd0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
15fe0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
15ff0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
16000 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
16010 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
16020 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
16030 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
16040 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
16050 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
16060 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
16070 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
16080 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
16090 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
160a0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
160b0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
160c0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
160d0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
160e0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
160f0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
16100 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
16110 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
16120 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16130 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
16140 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
16150 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
16160 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
16170 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
16180 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
16190 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
161a0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
161b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
161c0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
161d0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
161e0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
161f0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
16200 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
16210 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
16220 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
16230 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
16240 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
16250 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
16260 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16270 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
16280 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
16290 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
162a0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
162b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
162c0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
162d0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
162e0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
162f0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
16300 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
16310 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
16320 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
16330 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
16340 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
16350 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
16360 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
16370 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
16380 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
16390 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
163a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
163b0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
163c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
163d0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
163e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
163f0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
16400 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
16410 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
16420 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
16430 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
16440 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
16450 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
16460 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
16470 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
16480 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
16490 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
164a0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
164b0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
164c0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
164d0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
164e0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
164f0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
16500 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
16510 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
16520 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
16530 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
16540 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
16550 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
16560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16570 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
16580 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
16590 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
165a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
165b0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
165c0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
165d0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
165e0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
165f0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
16600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16610 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
16620 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
16630 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
16640 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
16650 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
16660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
16670 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16680 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
16690 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
166a0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
166b0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
166c0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
166d0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
166e0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
166f0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
16700 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
16710 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
16720 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
16730 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
16740 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
16750 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
16760 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
16770 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
16780 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
16790 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
167a0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
167b0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
167c0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
167d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
167e0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
167f0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
16800 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
16810 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
16820 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
16830 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
16840 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
16850 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
16860 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
16870 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
16880 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
16890 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
168a0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
168b0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
168c0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
168d0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
168e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
168f0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
16900 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
16910 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
16920 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
16930 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
16940 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
16950 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
16960 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
16970 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
16980 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
16990 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
169a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
169b0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
169c0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
169d0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
169e0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
169f0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
16a00 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
16a10 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
16a20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
16a30 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
16a40 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
16a50 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
16a60 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
16a70 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
16a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
16a90 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
16aa0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
16ab0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
16ac0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
16ad0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
16ae0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
16af0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
16b00 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
16b10 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
16b20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
16b30 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
16b40 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
16b50 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
16b60 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
16b70 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
16b80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
16b90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
16ba0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
16bb0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
16bc0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
16bd0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
16be0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
16bf0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
16c00 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
16c10 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
16c20 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
16c30 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
16c40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
16c50 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
16c60 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
16c70 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
16c80 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
16c90 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
16ca0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
16cb0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
16cc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
16cd0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
16ce0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
16cf0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
16d00 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
16d10 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
16d20 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
16d30 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
16d40 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
16d50 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
16d60 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
16d70 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
16d80 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
16d90 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
16da0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
16db0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
16dc0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
16dd0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
16de0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
16df0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
16e00 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
16e10 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
16e20 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
16e30 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
16e40 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
16e50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16e60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
16e70 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
16e80 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
16e90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16ea0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
16eb0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
16ec0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
16ed0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
16ee0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16ef0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
16f00 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
16f10 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
16f20 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
16f30 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
16f40 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
16f50 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
16f60 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
16f70 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
16f80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16f90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
16fa0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
16fb0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
16fc0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
16fd0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
16fe0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
16ff0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
17000 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
17010 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
17020 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
17030 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17040 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
17050 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
17060 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17070 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
17080 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
17090 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
170a0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
170b0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
170c0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
170d0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
170e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
170f0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
17100 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
17110 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
17120 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
17130 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17140 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
17150 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
17160 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
17170 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
17180 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
17190 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
171a0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
171b0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
171c0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
171d0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
171e0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
171f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
17200 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
17210 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
17220 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
17230 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
17240 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
17250 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
17260 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
17270 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
17280 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
17290 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
172a0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
172b0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
172c0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
172d0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
172e0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
172f0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
17300 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17310 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
17320 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
17330 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17340 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
17350 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
17360 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
17370 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
17380 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
17390 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
173a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
173b0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
173c0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
173d0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
173e0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
173f0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
17400 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
17410 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
17420 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
17430 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
17440 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
17450 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
17460 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
17470 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
17480 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
17490 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
174a0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
174b0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
174c0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
174d0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
174e0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
174f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
17500 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
17510 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
17520 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
17530 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
17540 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
17550 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
17560 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
17570 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
17580 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17590 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  , ...);.SQLITE_A
175a0 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
175b0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
175c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
175d0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
175e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
175f0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
17600 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
17610 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
17620 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
17630 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
17640 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
17650 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
17660 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17670 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17680 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17690 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
176a0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
176b0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
176c0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
176d0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
176e0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
176f0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
17700 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
17710 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
17720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
17730 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
17740 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
17750 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
17760 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
17770 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17780 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17790 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
177a0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
177b0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
177c0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
177d0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
177e0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
177f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
17800 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
17810 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
17820 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17830 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
17840 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
17850 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
17860 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
17870 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17880 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17890 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
178a0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
178b0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
178c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
178d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
178e0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
178f0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
17900 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
17910 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
17920 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
17930 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
17940 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
17950 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17960 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
17970 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17980 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17990 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
179a0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
179b0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
179c0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
179d0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
179e0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
179f0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
17a00 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
17a10 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
17a20 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
17a30 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
17a40 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
17a50 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
17a60 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
17a70 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17a80 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17a90 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17aa0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
17ab0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
17ac0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
17ad0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
17ae0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
17af0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
17b00 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
17b10 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17b20 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17b30 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17b40 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17b50 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17b60 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17b70 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17b80 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17b90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17ba0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
17bb0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
17bc0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
17bd0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
17be0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
17bf0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17c00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17c10 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17c20 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17c30 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17c40 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17c50 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17c60 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17c70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17c80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17c90 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17ca0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
17cb0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17cc0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
17cd0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
17ce0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
17cf0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
17d00 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
17d10 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
17d20 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
17d30 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17d40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17d50 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17d60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17d70 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
17d80 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17d90 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
17da0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17db0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
17dc0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
17dd0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
17de0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
17df0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
17e00 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17e10 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
17e20 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
17e30 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17e40 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
17e50 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
17e60 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
17e70 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
17e80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
17e90 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17ea0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
17eb0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
17ec0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
17ed0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17ee0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17ef0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
17f00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
17f10 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17f20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17f40 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17f50 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
17f60 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
17f70 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
17f80 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
17f90 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
17fa0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
17fb0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
17fc0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
17fd0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
17fe0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
17ff0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
18000 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
18010 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
18020 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
18030 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
18040 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
18050 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
18060 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
18070 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
18080 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
18090 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
180a0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
180b0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
180c0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
180d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
180e0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
180f0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
18100 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
18110 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
18120 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
18130 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
18140 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
18150 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
18160 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
18170 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
18180 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
18190 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
181a0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
181b0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
181c0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
181d0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
181e0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
181f0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
18200 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
18210 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
18220 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
18230 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
18240 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
18250 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
18260 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
18270 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18280 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
18290 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
182a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
182b0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
182c0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
182d0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
182e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
182f0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
18300 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18310 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
18320 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
18330 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
18340 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
18350 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
18360 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18370 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18380 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
18390 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
183a0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
183b0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
183c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
183d0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
183e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
183f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
18400 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
18410 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
18420 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
18430 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
18440 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
18450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
18460 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
18470 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18480 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18490 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
184a0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
184b0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
184c0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
184d0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
184e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
184f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
18500 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
18510 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18520 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
18530 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
18540 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
18550 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
18560 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
18570 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
18580 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
18590 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
185a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
185b0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
185c0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
185d0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
185e0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
185f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
18600 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
18610 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
18620 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
18630 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
18640 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18650 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
18660 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
18670 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
18680 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
18690 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
186a0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
186b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
186c0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
186d0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
186e0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
186f0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
18700 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
18710 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
18720 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
18730 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
18740 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
18750 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
18760 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
18770 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
18780 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
18790 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
187a0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
187b0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
187c0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
187d0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
187e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
187f0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
18800 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
18810 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
18820 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18830 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
18840 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18850 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
18860 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
18870 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
18880 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
18890 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
188a0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
188b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
188c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
188d0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
188e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
188f0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18900 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
18910 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
18920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
18930 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
18940 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
18950 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
18960 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
18970 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
18980 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
18990 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
189a0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
189b0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
189c0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
189d0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
189e0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
189f0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
18a00 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
18a10 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
18a20 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
18a30 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
18a40 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
18a50 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
18a60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
18a70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
18a80 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
18a90 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
18aa0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
18ab0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
18ac0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
18ad0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
18ae0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
18af0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
18b00 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
18b10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
18b20 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
18b30 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
18b40 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
18b50 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
18b60 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
18b70 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
18b80 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
18b90 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
18ba0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
18bb0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
18bc0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18bd0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
18be0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
18bf0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
18c00 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
18c10 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
18c20 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
18c30 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
18c40 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
18c50 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
18c60 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
18c70 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
18c80 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
18c90 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
18ca0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
18cb0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
18cc0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
18cd0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
18ce0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
18cf0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
18d00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18d10 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
18d20 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
18d30 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
18d40 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
18d50 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
18d60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18d70 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18d80 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
18d90 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
18da0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
18db0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18dc0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18dd0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
18de0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
18df0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18e00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18e10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
18e20 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
18e30 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
18e40 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
18e50 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
18e60 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
18e70 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
18e80 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
18e90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18ea0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18eb0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
18ec0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
18ed0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
18ee0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18ef0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
18f00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
18f10 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
18f20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
18f30 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
18f40 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
18f50 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
18f60 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
18f70 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
18f80 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
18f90 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
18fa0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
18fb0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
18fc0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
18fd0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
18fe0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
18ff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19000 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
19010 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
19020 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
19030 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
19040 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
19050 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
19060 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
19070 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
19080 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
19090 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
190a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
190b0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
190c0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
190d0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
190e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
190f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
19100 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
19110 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
19120 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
19130 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19140 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
19150 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
19160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19170 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
19180 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
19190 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
191a0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
191b0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
191c0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
191d0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
191e0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
191f0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
19200 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19210 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19220 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19230 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
19240 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
19250 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
19260 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
19270 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
19280 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
19290 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
192a0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
192b0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
192c0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
192d0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
192e0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
192f0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
19300 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
19310 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
19320 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
19330 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
19340 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19350 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
19360 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
19370 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
19380 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
19390 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
193a0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
193b0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
193c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
193d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
193e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
193f0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
19400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
19410 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
19420 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
19430 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
19440 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
19450 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
19460 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
19470 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
19480 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
19490 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
194a0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
194b0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
194c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
194d0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
194e0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
194f0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
19500 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
19510 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
19520 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
19530 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
19540 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19550 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
19560 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
19570 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
19580 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
19590 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
195a0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
195b0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
195c0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
195d0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
195e0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
195f0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
19600 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
19610 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
19620 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
19630 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
19640 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
19650 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
19660 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19670 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
19680 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
19690 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
196a0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
196b0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
196c0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
196d0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
196e0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
196f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
19700 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
19710 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
19720 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
19730 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
19740 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
19750 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
19760 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
19770 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
19780 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
19790 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
197a0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
197b0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
197c0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
197d0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
197e0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
197f0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
19800 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
19810 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
19820 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
19830 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
19840 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
19850 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
19860 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
19870 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
19880 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
19890 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
198a0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
198b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
198c0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
198d0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
198e0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
198f0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
19900 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
19910 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
19920 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
19930 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
19940 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
19950 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
19960 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
19970 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
19980 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
19990 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
199a0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
199b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
199c0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
199d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
199e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
199f0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
19a00 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
19a10 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
19a20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
19a30 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
19a40 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
19a50 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
19a60 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19a70 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
19a80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19a90 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
19aa0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19ab0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
19ac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19ad0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19ae0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19af0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
19b00 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
19b10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
19b20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19b30 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
19b40 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19b50 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19b60 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19b70 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19b80 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
19b90 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
19ba0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
19bb0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
19bc0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
19bd0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
19be0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
19bf0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
19c00 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
19c10 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
19c20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
19c30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c40 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
19c50 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
19c60 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
19c70 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
19c80 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
19c90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19ca0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
19cb0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
19cc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19cd0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
19ce0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
19cf0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
19d00 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
19d10 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
19d20 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
19d30 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
19d40 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
19d50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
19d60 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
19d70 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
19d80 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
19d90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
19da0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
19db0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
19dc0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
19dd0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
19de0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
19df0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19e00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19e10 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
19e20 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
19e30 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
19e40 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
19e50 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
19e60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
19e70 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
19e80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
19e90 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
19ea0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
19eb0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
19ec0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
19ed0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19ee0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
19ef0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
19f00 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
19f10 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
19f20 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
19f30 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
19f40 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
19f50 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
19f60 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
19f70 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
19f80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
19f90 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
19fa0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
19fb0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
19fc0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
19fd0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
19fe0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
19ff0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1a000 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1a010 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1a020 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1a030 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1a040 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1a050 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1a060 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1a070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1a080 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1a090 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1a0a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a0b0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a0c0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a0d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a0e0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a0f0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a100 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a110 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a120 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a140 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a150 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a160 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a170 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a180 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a190 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1a1a0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1a1b0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1a1c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a1d0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1a1e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1a1f0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1a200 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1a210 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1a220 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1a230 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1a240 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1a250 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1a260 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1a270 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1a280 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1a290 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1a2a0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1a2b0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1a2c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a2d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1a2e0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1a2f0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1a300 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a310 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1a320 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1a330 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1a340 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1a350 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1a360 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1a370 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a380 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1a390 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1a3a0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1a3b0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1a3c0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1a3d0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1a3e0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1a3f0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1a400 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1a410 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1a420 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1a430 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1a440 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a450 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1a460 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1a470 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1a480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a490 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1a4a0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1a4b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1a4c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a4d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a4e0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1a4f0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1a500 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1a510 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1a530 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1a540 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1a550 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1a560 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1a570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a580 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1a590 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1a5a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1a5b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a5c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a5d0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1a5e0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1a5f0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1a600 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1a610 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a620 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1a630 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1a640 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1a650 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a660 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1a670 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1a680 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1a690 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1a6a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1a6b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1a6c0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1a6d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1a6e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1a6f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a700 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1a710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1a720 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1a730 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a740 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a750 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1a760 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1a770 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a780 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a790 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a7a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1a7b0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1a7c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a7d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a7e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a7f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1a800 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1a810 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1a820 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1a830 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a840 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1a850 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1a860 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a870 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a890 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1a8a0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1a8b0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1a8c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a8d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a8e0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1a8f0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1a900 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1a910 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a930 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1a940 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1a950 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1a960 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1a970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a980 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1a990 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1a9a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1a9b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a9c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1a9d0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1a9e0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1a9f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1aa00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1aa10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1aa20 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1aa30 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1aa40 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1aa50 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1aa60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1aa70 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1aa80 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1aa90 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1aaa0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1aab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1aac0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1aad0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1aae0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1aaf0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ab00 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1ab10 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1ab20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1ab30 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1ab40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ab50 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1ab60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ab70 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1ab80 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1ab90 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1aba0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1abb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1abc0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1abd0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1abe0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1abf0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1ac00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1ac10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1ac20 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1ac30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ac40 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1ac50 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1ac60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1ac70 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1ac80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ac90 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1aca0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1acb0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1acc0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1acd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ace0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1acf0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1ad00 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ad10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ad20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ad30 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1ad40 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1ad50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ad60 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1ad70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ad80 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1ad90 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1ada0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1adb0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1adc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1add0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1ade0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1adf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1ae00 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1ae10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ae20 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1ae30 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1ae40 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1ae50 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1ae60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ae70 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1ae80 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1ae90 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1aea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1aeb0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1aec0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1aed0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1aee0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1aef0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1af00 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1af10 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1af20 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1af30 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1af40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1af50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1af60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1af70 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1af80 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1af90 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1afa0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1afb0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1afc0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1afd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1afe0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1aff0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1b000 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1b010 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1b020 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1b030 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1b040 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1b050 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1b060 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1b070 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1b080 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1b090 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1b0a0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1b0b0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1b0c0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1b0d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1b0e0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1b0f0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1b100 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1b110 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1b120 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1b130 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b140 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b150 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1b160 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b170 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1b180 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1b190 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1b1a0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1b1b0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1b1c0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1b1d0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1b1e0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1b1f0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1b200 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1b210 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1b220 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1b230 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1b240 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1b250 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1b260 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1b270 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1b280 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1b290 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1b2a0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1b2b0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1b2c0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1b2d0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1b2e0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1b2f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1b300 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1b310 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1b320 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1b330 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1b340 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1b350 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1b360 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1b370 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1b380 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1b390 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1b3a0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1b3b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1b3c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1b3d0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1b3e0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1b3f0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1b400 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1b410 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1b420 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1b430 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1b440 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1b450 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1b460 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1b470 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1b480 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1b490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b4a0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1b4b0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1b4c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1b4d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1b4e0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1b4f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1b500 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1b510 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1b520 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1b530 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1b540 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1b550 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b560 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b570 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b580 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1b590 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b5a0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1b5b0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1b5c0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1b5d0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1b5e0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1b5f0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1b600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1b610 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1b620 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1b630 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1b640 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1b650 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1b660 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1b670 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b680 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1b690 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1b6a0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1b6b0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1b6c0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1b6d0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1b6e0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1b6f0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1b700 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1b710 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1b720 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1b730 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b740 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1b750 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1b760 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1b770 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1b780 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1b790 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1b7a0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1b7b0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1b7c0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1b7d0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1b7e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1b7f0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1b800 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1b810 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b820 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1b830 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b840 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1b850 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1b860 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1b870 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1b880 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1b890 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1b8a0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1b8b0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1b8c0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1b8d0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1b8e0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b8f0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b900 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b920 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b930 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1b940 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1b950 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1b960 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1b970 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b980 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1b990 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1b9a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1b9b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1b9c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1b9d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
1b9e0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1b9f0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1ba00 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1ba10 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1ba20 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1ba30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1ba40 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1ba50 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1ba60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1ba70 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1ba80 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1ba90 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1baa0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1bab0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1bac0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1bad0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1bae0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1baf0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1bb00 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1bb10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bb20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1bb30 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1bb40 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1bb50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1bb60 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1bb70 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1bb80 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1bb90 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1bba0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1bbb0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1bbc0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1bbd0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1bbe0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1bbf0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1bc00 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1bc10 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1bc20 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1bc30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1bc40 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1bc50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1bc60 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1bc70 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1bc80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1bc90 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1bca0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1bcb0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1bcc0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1bcd0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1bce0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1bcf0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1bd00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1bd10 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1bd20 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1bd30 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1bd40 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1bd50 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1bd60 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1bd70 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1bd80 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1bd90 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1bda0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1bdb0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1bdc0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1bdd0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1bde0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1bdf0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1be00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1be10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1be20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1be30 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1be40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1be50 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1be60 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1be70 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1be80 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1be90 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1bea0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1beb0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1bec0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1bed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1bee0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1bef0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1bf00 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1bf10 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1bf20 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1bf30 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1bf40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bf50 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1bf60 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1bf70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1bf80 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1bf90 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1bfa0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1bfb0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1bfc0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1bfd0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1bfe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1bff0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1c000 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1c010 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1c020 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1c030 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1c040 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1c050 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1c060 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1c070 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c080 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c090 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1c0a0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1c0b0 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  CACHE],.** and/o
1c0c0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1c0d0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1c0e0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1c0f0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1c100 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1c110 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c120 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1c130 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1c140 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1c150 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1c160 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1c170 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1c180 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1c190 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1c1a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c1b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1c1c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c1d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1c1e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1c1f0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1c200 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1c210 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1c220 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1c230 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c240 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1c250 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1c260 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1c270 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1c280 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1c290 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1c2a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1c2b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c2c0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1c2d0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1c2e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1c2f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c300 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1c310 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1c320 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1c330 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1c340 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1c350 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1c360 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1c370 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1c380 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1c390 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1c3a0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1c3b0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1c3c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c3d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1c3e0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1c3f0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1c400 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1c410 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1c420 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1c430 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1c440 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1c450 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1c460 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1c470 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1c480 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1c490 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1c4a0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1c4b0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1c4c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c4d0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1c4e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1c4f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1c500 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1c510 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1c520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1c530 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1c540 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1c550 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1c560 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1c570 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1c580 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1c590 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1c5a0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1c5b0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1c5c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1c5d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1c5e0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1c5f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1c600 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1c610 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1c620 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1c630 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1c640 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1c650 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1c660 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1c670 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1c680 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1c690 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1c6a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1c6b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c6c0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1c6d0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1c6e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1c6f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1c700 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1c710 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1c720 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1c730 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1c740 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1c750 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1c760 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1c770 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1c780 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c790 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1c7a0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1c7b0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1c7c0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1c7d0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1c7e0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1c7f0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1c800 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1c810 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1c820 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1c830 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1c840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1c850 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1c860 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1c870 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1c880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c890 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1c8a0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1c8b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1c8c0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1c8d0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1c8e0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1c8f0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1c900 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1c910 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1c920 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1c930 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1c940 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1c950 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1c960 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1c970 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1c980 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1c990 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1c9a0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1c9b0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1c9c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1c9d0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1c9e0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1c9f0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1ca00 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1ca10 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1ca20 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1ca30 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1ca40 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1ca50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1ca60 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1ca70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ca80 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1ca90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1caa0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1cab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cac0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1cad0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1cae0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1caf0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1cb00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1cb10 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1cb20 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1cb30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1cb40 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1cb50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1cb60 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1cb70 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1cb80 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1cb90 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1cba0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1cbb0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1cbc0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1cbd0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1cbe0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1cbf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1cc00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1cc10 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1cc20 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1cc30 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1cc40 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1cc50 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1cc60 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1cc70 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1cc80 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1cc90 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1cca0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1ccb0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1ccc0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1ccd0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1cce0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ccf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1cd00 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cd10 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1cd20 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1cd30 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1cd40 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1cd50 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1cd60 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1cd70 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1cd80 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1cd90 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cda0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1cdb0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1cdc0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1cdd0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1cde0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1cdf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1ce00 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1ce10 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
1ce20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
1ce30 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1ce40 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1ce50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1ce60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1ce70 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1ce80 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1ce90 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1cea0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1ceb0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1cec0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1ced0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1cee0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1cef0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1cf00 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1cf10 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1cf20 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1cf30 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1cf40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cf50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1cf60 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1cf70 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1cf80 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1cf90 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1cfa0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1cfb0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1cfc0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1cfd0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1cfe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cff0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1d000 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1d010 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1d020 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1d030 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1d040 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1d050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1d060 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1d070 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1d080 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1d090 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1d0a0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1d0b0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1d0c0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1d0d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1d0e0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1d0f0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1d100 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1d110 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1d120 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1d130 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1d140 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1d150 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1d160 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1d170 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1d180 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1d190 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1d1a0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1d1b0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1d1c0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1d1d0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1d1e0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1d1f0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1d200 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1d210 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1d220 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1d230 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1d240 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1d250 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1d260 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1d270 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1d280 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d290 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1d2a0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1d2b0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1d2c0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1d2d0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d2e0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1d2f0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1d300 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1d310 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1d320 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1d330 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1d340 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1d350 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1d360 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1d370 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1d380 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1d390 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1d3a0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1d3b0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1d3c0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1d3d0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1d3e0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1d3f0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1d400 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1d410 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1d420 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1d430 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1d440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d450 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1d460 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1d470 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1d480 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1d490 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1d4a0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1d4b0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1d4c0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1d4d0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1d4e0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1d4f0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1d500 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1d510 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1d520 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1d530 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1d540 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1d550 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1d560 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1d570 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1d580 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1d590 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1d5a0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1d5b0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1d5c0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1d5d0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1d5e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d5f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1d600 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1d610 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d620 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1d630 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1d640 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
1d650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1d660 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1d670 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
1d680 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
1d690 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1d6a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1d6b0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1d6c0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
1d6d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1d6e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d6f0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1d700 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1d710 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1d720 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1d730 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1d740 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1d750 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1d760 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1d770 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1d780 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1d790 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1d7a0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1d7b0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1d7c0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1d7d0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1d7e0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1d7f0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1d800 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1d810 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1d820 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1d830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d840 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1d850 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1d860 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1d870 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1d880 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1d890 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1d8a0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1d8b0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1d8c0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1d8d0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1d8e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1d8f0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1d900 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1d910 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1d920 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1d930 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1d940 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1d950 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1d960 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1d970 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1d980 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1d990 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1d9a0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1d9b0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1d9c0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1d9d0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1d9e0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1d9f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1da00 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1da10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1da20 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1da30 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1da40 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1da50 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
1da60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1da70 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1da80 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1da90 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1daa0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1dab0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1dac0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1dad0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1dae0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1daf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1db00 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1db10 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1db20 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1db30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1db40 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1db50 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1db60 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1db70 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1db80 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1db90 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1dba0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1dbb0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1dbc0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1dbd0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
1dbe0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1dbf0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1dc00 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1dc10 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
1dc20 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
1dc30 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
1dc40 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
1dc50 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
1dc60 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1dc70 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1dc80 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1dc90 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
1dca0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
1dcb0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
1dcc0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
1dcd0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
1dce0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1dcf0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1dd00 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1dd10 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1dd20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1dd30 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1dd40 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1dd50 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1dd60 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1dd70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1dd80 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
1dd90 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1dda0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
1ddb0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
1ddc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
1ddd0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
1dde0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
1ddf0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
1de00 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
1de10 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
1de20 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
1de30 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
1de40 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
1de50 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
1de60 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
1de70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1de80 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
1de90 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1dea0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1deb0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1dec0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1ded0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1dee0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1def0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1df00 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1df10 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1df20 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1df30 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1df40 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1df50 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1df60 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1df70 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1df80 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1df90 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1dfa0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1dfb0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1dfc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1dfd0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1dfe0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1dff0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1e000 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1e010 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1e020 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1e030 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1e040 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1e050 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1e060 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1e070 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1e080 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1e090 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1e0a0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1e0b0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1e0c0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1e0d0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1e0e0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1e0f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e100 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1e110 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1e120 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1e130 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1e140 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1e150 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1e160 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1e170 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1e180 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1e190 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1e1a0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1e1b0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1e1c0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1e1d0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1e1e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1e1f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1e200 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
1e210 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
1e220 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
1e230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e240 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
1e250 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
1e260 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1e270 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
1e280 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
1e290 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1e2a0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1e2b0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
1e2c0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
1e2d0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
1e2e0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
1e2f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1e300 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
1e310 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
1e320 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1e330 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
1e340 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
1e350 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1e360 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
1e370 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
1e380 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
1e390 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1e3a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1e3b0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e3c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
1e3d0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
1e3e0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
1e3f0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
1e400 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  <dd>)^.**.** ^(<
1e410 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e420 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1e430 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e440 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1e450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
1e460 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
1e470 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e480 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1e490 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e4a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e4b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1e4c0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1e4d0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1e4e0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1e4f0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1e500 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1e510 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1e520 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1e530 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1e540 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1e550 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e560 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1e570 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1e580 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1e590 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1e5a0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1e5b0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
1e5c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e5d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1e5e0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1e5f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e600 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1e610 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1e620 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1e630 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e640 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e650 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1e660 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e670 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1e680 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1e690 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1e6a0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1e6b0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1e6c0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
1e6d0 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
1e6e0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
1e6f0 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
1e700 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
1e710 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
1e720 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
1e730 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
1e740 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e750 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1e760 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1e770 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e780 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1e790 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1e7a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e7b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1e7c0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1e7d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e7e0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1e7f0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1e800 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
1e810 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e820 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1e830 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
1e840 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e850 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
1e860 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
1e870 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
1e880 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
1e890 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
1e8a0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e8b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1e8c0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1e8d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e8e0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
1e8f0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
1e900 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
1e910 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ement.)^.**.** ^
1e920 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e930 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
1e940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e950 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1e960 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
1e970 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
1e980 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1e990 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e9a0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1e9b0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1e9c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e9d0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1e9e0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1e9f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1ea00 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1ea10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1ea20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ea30 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1ea40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1ea50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ea60 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1ea70 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1ea80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ea90 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1eaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eab0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1eac0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1ead0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1eae0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1eaf0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1eb00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb10 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1eb20 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1eb30 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1eb40 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1eb50 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1eb60 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1eb70 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
1eb80 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1eb90 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
1eba0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
1ebb0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1ebc0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1ebd0 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
1ebe0 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
1ebf0 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
1ec00 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1ec10 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1ec20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1ec30 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1ec40 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1ec50 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1ec60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1ec70 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1ec80 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
1ec90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1eca0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
1ecb0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
1ecc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1ecd0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1ece0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1ecf0 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
1ed00 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1ed10 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
1ed20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
1ed30 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
1ed40 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1ed50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1ed60 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1ed70 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1ed80 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1ed90 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1eda0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1edb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1edc0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1edd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1ede0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1edf0 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1ee00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ee10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ee20 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1ee30 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1ee40 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
1ee50 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
1ee60 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
1ee70 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1ee80 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
1ee90 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1eea0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
1eeb0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1eec0 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
1eed0 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
1eee0 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
1eef0 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
1ef00 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1ef10 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
1ef20 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
1ef30 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
1ef40 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
1ef50 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
1ef60 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
1ef70 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
1ef80 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
1ef90 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
1efa0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
1efb0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
1efc0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
1efd0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
1efe0 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
1eff0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
1f000 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
1f010 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1f020 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
1f030 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1f040 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1f050 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1f060 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1f070 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
1f080 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
1f090 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tes..**.** ^If p
1f0a0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1f0b0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
1f0c0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1f0d0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1f0e0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
1f0f0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1f100 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1f110 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1f120 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
1f130 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
1f140 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1f150 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1f160 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1f170 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
1f180 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
1f190 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
1f1a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1f1b0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1f1c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f1d0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1f1e0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1f1f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1f200 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
1f210 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
1f220 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
1f230 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
1f240 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1f250 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
1f260 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
1f270 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
1f280 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1f290 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1f2a0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
1f2b0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
1f2c0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1f2d0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
1f2e0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
1f2f0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1f300 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f310 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
1f320 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1f330 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
1f340 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
1f350 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
1f360 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
1f370 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
1f380 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
1f390 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
1f3a0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
1f3b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1f3c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1f3d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1f3e0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
1f3f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f400 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
1f410 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
1f420 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
1f430 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
1f440 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
1f450 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
1f460 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1f470 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
1f480 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
1f490 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
1f4a0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1f4b0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
1f4c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
1f4d0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
1f4e0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
1f4f0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
1f500 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
1f510 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
1f520 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
1f530 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
1f540 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
1f550 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
1f560 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
1f570 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
1f580 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1f590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
1f5a0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
1f5b0 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
1f5c0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
1f5d0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
1f5e0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
1f5f0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
1f600 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
1f610 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1f620 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
1f630 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
1f640 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
1f650 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1f660 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1f670 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1f680 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f690 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1f6a0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1f6b0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1f6c0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1f6d0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1f6e0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1f6f0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1f700 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f710 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1f720 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1f730 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1f740 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1f750 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1f760 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1f770 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1f780 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1f790 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1f7a0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1f7b0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1f7c0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1f7d0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1f7e0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1f7f0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1f800 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1f810 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1f820 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1f830 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1f840 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
1f850 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
1f860 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
1f870 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1f880 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
1f890 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
1f8a0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
1f8b0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
1f8c0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
1f8d0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
1f8e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
1f8f0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
1f900 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
1f910 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
1f920 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
1f930 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
1f940 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
1f950 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1f960 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
1f970 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
1f980 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
1f990 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
1f9a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1f9b0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
1f9c0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
1f9d0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
1f9e0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
1f9f0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
1fa00 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
1fa10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1fa20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
1fa30 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
1fa40 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
1fa50 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
1fa60 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
1fa70 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
1fa80 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
1fa90 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
1faa0 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f  ENABLE_STAT2] co
1fab0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1fac0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
1fad0 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
1fae0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
1faf0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1fb00 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
1fb10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1fb20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1fb30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1fb40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1fb50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1fb60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1fb70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1fb80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1fb90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1fba0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1fbb0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1fbc0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1fbd0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1fbe0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1fbf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1fc00 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1fc10 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1fc20 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1fc30 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
1fc40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1fc50 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1fc60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1fc70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1fc80 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1fc90 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1fca0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1fcb0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1fcc0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1fcd0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1fce0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1fcf0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1fd00 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1fd10 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1fd20 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1fd30 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1fd40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1fd50 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1fd60 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1fd70 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1fd80 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
1fd90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1fda0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1fdb0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1fdc0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1fdd0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1fde0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1fdf0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1fe00 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1fe10 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1fe20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1fe30 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1fe40 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1fe50 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1fe60 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1fe70 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1fe80 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1fe90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1fea0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1feb0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1fec0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1fed0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
1fee0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1fef0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1ff00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1ff10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1ff20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1ff30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1ff40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1ff50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1ff60 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1ff70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1ff80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1ff90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ffa0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1ffb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1ffc0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1ffd0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1ffe0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1fff0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
20000 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
20010 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
20020 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
20030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20040 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
20050 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
20060 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
20070 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
20080 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
20090 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
200a0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
200b0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
200c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
200d0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
200e0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
200f0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
20100 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
20110 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
20120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20130 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
20140 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
20150 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
20160 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
20170 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
20180 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
20190 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
201a0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
201b0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
201c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
201d0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
201e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
201f0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
20200 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
20210 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
20220 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
20230 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
20240 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
20250 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
20260 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
20270 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
20280 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
202a0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
202b0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
202c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
202d0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
202e0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
202f0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
20300 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
20310 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
20320 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
20330 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
20340 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
20350 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
20360 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
20370 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
20380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20390 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
203a0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
203b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
203c0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
203d0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
203e0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
203f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
20400 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
20410 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
20420 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
20430 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
20440 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
20450 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
20460 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
20470 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
20480 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
20490 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
204a0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
204b0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
204c0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
204d0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
204e0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
204f0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
20500 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
20510 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
20520 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
20530 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
20540 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
20550 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
20560 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
20570 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
20580 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
20590 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
205a0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
205b0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
205c0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
205d0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
205e0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
205f0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
20600 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
20610 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
20620 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
20630 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
20640 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
20650 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
20660 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
20670 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
20680 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
20690 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
206a0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
206b0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
206c0 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
206d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
206e0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
206f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
20700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20710 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
20720 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
20730 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
20740 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20750 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
20760 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20770 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
20780 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
20790 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
207a0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
207b0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
207c0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
207d0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
207e0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
207f0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
20800 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
20810 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
20820 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
20830 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20840 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
20850 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
20860 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
20870 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
20880 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
20890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
208a0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
208b0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
208c0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
208d0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
208e0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
208f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20900 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
20910 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
20920 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
20930 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
20940 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
20950 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
20960 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
20970 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
20980 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
20990 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
209a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
209b0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
209c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
209d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
209e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
209f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
20a00 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
20a10 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
20a20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
20a30 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
20a40 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
20a50 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
20a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20a70 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
20a80 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
20a90 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
20aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20ab0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
20ac0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
20ad0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
20ae0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
20af0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
20b00 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
20b10 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
20b20 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
20b30 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
20b40 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
20b50 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
20b60 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
20b70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
20b80 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
20b90 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
20ba0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
20bb0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
20bc0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
20bd0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
20be0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
20bf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
20c00 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
20c10 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
20c20 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
20c30 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
20c40 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
20c50 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
20c60 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
20c70 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
20c80 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
20c90 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
20ca0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
20cb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20cc0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
20cd0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
20ce0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
20cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
20d00 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
20d10 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
20d20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
20d30 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
20d40 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
20d50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
20d60 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
20d70 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
20d80 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
20d90 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
20da0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
20db0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
20dc0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
20dd0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
20de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20df0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
20e00 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
20e10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
20e20 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
20e30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20e40 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
20e50 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
20e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
20e70 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
20e80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
20e90 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
20ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20eb0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
20ec0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
20ed0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
20ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
20ef0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
20f00 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
20f10 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
20f20 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
20f30 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
20f40 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
20f50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20f60 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
20f70 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
20f80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
20f90 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
20fa0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
20fb0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
20fc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20fd0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
20fe0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20ff0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
21000 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
21010 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
21020 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
21030 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
21040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
21050 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
21060 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
21070 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
21080 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
21090 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
210a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
210b0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
210c0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
210d0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
210e0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
210f0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
21100 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
21110 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
21120 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
21130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21140 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
21150 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
21160 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
21170 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
21180 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
21190 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
211a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
211b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
211c0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
211d0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
211e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
211f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
21200 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
21210 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
21220 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21230 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
21240 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
21250 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
21260 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
21270 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
21280 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
21290 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
212a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
212b0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
212c0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
212d0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
212e0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
212f0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
21300 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
21310 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
21320 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
21330 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
21340 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
21350 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
21360 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
21370 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
21380 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
21390 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
213a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
213b0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
213c0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
213d0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
213e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
213f0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
21400 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
21410 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21420 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
21430 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
21440 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
21450 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21460 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
21470 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
21480 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
21490 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
214a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
214b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
214c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
214d0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
214e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
214f0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
21500 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
21510 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
21520 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
21530 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
21540 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
21550 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
21560 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
21570 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
21580 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
21590 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
215a0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
215b0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
215c0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
215d0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
215e0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
215f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
21600 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21610 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
21620 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
21630 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
21640 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
21650 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
21660 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
21670 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
21680 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
21690 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
216a0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
216b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
216c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
216d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
216e0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
216f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
21700 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
21710 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
21720 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
21730 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
21740 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
21750 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
21760 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
21770 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21780 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
21790 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
217a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
217b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
217c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
217d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
217e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
217f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
21800 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21810 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
21820 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
21830 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
21840 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
21850 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
21860 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
21870 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nator..**.** ^Th
21880 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
21890 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
218a0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
218b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
218c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
218d0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
218e0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
218f0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
21900 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
21910 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
21920 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
21930 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
21940 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
21950 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
21960 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
21970 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
21980 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
21990 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
219a0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
219b0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
219c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
219d0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
219e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
219f0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
21a00 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
21a10 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
21a20 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
21a30 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
21a40 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
21a50 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
21a60 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
21a70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
21a80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
21a90 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
21aa0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
21ab0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
21ac0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
21ad0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
21ae0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
21af0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
21b00 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
21b10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21b20 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
21b30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
21b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
21b50 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
21b60 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
21b70 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
21b80 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
21b90 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
21ba0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
21bb0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
21bc0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
21bd0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
21be0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
21bf0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
21c00 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
21c10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
21c20 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
21c30 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
21c40 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
21c50 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
21c60 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
21c70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
21c80 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
21c90 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
21ca0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
21cb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
21cc0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
21cd0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
21ce0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
21cf0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
21d00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
21d10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
21d20 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
21d30 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
21d40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21d50 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
21d60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21d70 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
21d80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21d90 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
21da0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
21db0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
21dc0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
21dd0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
21de0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
21df0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
21e00 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
21e10 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
21e20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21e30 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
21e40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
21e50 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
21e60 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
21e70 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
21e80 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
21e90 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
21ea0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
21eb0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
21ec0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
21ed0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
21ee0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
21ef0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
21f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
21f10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
21f20 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
21f30 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
21f40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
21f50 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
21f60 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
21f70 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
21f80 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
21f90 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
21fa0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
21fb0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
21fc0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
21fd0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
21fe0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22000 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
22010 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22020 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
22030 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
22040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22050 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
22060 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
22070 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
22080 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22090 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
220a0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
220b0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
220c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
220d0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
220e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
220f0 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
22100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22110 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
22120 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
22130 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
22140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
22150 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
22160 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
22170 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
22180 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22190 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
221a0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
221b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
221c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
221d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
221e0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
221f0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
22200 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
22210 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22220 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
22230 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
22240 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
22250 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
22260 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
22270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
22280 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22290 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
222a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
222b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
222c0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
222d0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
222e0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
222f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22300 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
22310 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
22320 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
22330 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
22340 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
22350 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
22360 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
22370 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
22380 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
22390 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
223a0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
223b0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
223c0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
223d0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
223e0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
223f0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
22400 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22410 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
22420 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
22430 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
22440 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
22450 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
22460 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
22470 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
22480 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
22490 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
224a0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
224b0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
224c0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
224d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
224e0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
224f0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
22500 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
22510 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
22520 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
22530 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
22540 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22550 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22560 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22570 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22580 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
22590 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
225a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
225b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
225c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
225d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
225e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
225f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
22600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22610 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
22620 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
22630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
22640 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
22650 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
22660 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
22670 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
22680 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
22690 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
226a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
226b0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
226c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
226d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
226e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
226f0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
22700 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
22710 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
22720 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
22730 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
22740 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
22750 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
22760 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
22770 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
22780 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
22790 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
227a0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
227b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
227c0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
227d0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
227e0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
227f0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
22800 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
22810 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
22820 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
22830 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
22840 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
22850 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
22860 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
22870 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
22880 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
22890 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
228a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
228b0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
228c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
228d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
228e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
228f0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
22900 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
22910 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
22920 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
22930 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
22940 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
22950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22960 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22980 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
22990 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
229a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
229b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
229c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
229d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
229e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
229f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
22a00 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
22a10 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
22a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22a30 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
22a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
22a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22a60 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
22a70 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
22a80 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
22a90 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
22aa0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
22ab0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
22ac0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
22ad0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
22ae0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
22af0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
22b00 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
22b10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22b20 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
22b30 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
22b40 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
22b50 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
22b60 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
22b70 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
22b80 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
22b90 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
22ba0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
22bb0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22bc0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
22bd0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
22be0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22bf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22c00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22c10 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22c20 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22c30 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
22c40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22c50 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
22c60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22c70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22c80 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
22c90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
22ca0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
22cb0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
22cc0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
22cd0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
22ce0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
22cf0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
22d00 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
22d10 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
22d20 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
22d30 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
22d40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
22d50 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
22d60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
22d70 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
22d80 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
22d90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
22da0 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
22db0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
22dc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
22dd0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
22de0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
22df0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
22e00 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
22e10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22e20 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
22e30 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
22e40 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
22e50 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
22e60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
22e70 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
22e80 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
22e90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22ea0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
22eb0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
22ec0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
22ed0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
22ee0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
22ef0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
22f00 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
22f10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22f20 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
22f30 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
22f40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22f50 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
22f60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22f70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
22f80 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
22f90 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
22fa0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
22fb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22fc0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
22fd0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
22fe0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
22ff0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
23000 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23010 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
23020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23030 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
23040 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
23050 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
23060 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
23070 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
23080 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23090 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
230a0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
230b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
230c0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
230d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
230e0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
230f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
23100 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
23110 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
23120 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
23130 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
23140 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
23150 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
23160 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
23170 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
23180 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
23190 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
231a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
231b0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
231c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
231d0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
231e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
231f0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
23200 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
23210 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
23220 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
23230 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
23240 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23250 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
23260 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
23270 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
23280 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23290 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
232a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
232b0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
232c0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
232d0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
232e0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
232f0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
23300 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
23310 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
23320 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
23330 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
23340 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
23350 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
23360 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
23370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
23380 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
23390 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
233a0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
233b0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
233c0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
233d0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
233e0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
233f0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
23400 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
23410 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
23420 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
23430 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
23440 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
23450 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
23460 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
23470 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
23480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23490 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
234a0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
234b0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
234c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
234d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
234e0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
234f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23500 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
23510 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
23520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
23530 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
23540 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
23550 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
23560 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
23570 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
23580 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
23590 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
235a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
235b0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
235c0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
235d0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
235e0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
235f0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
23600 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
23610 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
23620 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
23630 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
23640 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
23650 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
23660 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
23670 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23680 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
23690 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
236a0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
236b0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
236c0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
236d0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
236e0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
236f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23700 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
23710 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
23720 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23730 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
23740 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
23750 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
23760 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
23770 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
23780 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
23790 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
237a0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
237b0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
237c0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
237d0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
237e0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
237f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
23800 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
23810 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
23820 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
23830 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
23840 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
23850 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
23860 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
23870 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
23880 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
23890 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
238a0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
238b0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
238c0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
238d0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
238e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
238f0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
23900 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
23910 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
23920 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
23930 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
23940 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
23950 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
23960 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
23970 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
23980 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
23990 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
239a0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
239b0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
239c0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
239d0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
239e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
239f0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
23a00 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
23a10 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
23a20 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
23a30 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
23a40 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
23a50 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
23a60 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
23a70 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
23a80 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
23a90 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
23aa0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
23ab0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
23ac0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
23ad0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
23ae0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
23af0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
23b00 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
23b10 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
23b20 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
23b30 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
23b40 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
23b50 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
23b60 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
23b70 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
23b80 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
23b90 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
23ba0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
23bb0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
23bc0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
23bd0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
23be0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
23bf0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
23c00 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
23c10 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
23c20 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
23c30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
23c40 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
23c50 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
23c60 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
23c70 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
23c80 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
23c90 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
23ca0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
23cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23cc0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
23cd0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
23ce0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
23cf0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
23d00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
23d10 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
23d20 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
23d30 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
23d40 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23d50 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
23d60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
23d70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23d80 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
23d90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23da0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
23db0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23dc0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23dd0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
23de0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
23df0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
23e00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23e10 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
23e20 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
23e30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
23e40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
23e50 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
23e60 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23e70 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
23e80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
23e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23ea0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
23eb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
23ec0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
23ed0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23ee0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
23ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23f00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23f10 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
23f20 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
23f30 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
23f40 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
23f50 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
23f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23f70 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
23f80 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
23f90 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
23fa0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23fb0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
23fc0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
23fd0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
23fe0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
23ff0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
24000 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
24010 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
24020 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
24030 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
24040 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
24050 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
24060 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
24070 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
24080 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24090 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
240a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
240b0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
240c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
240d0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
240e0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
240f0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
24100 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
24110 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
24120 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
24130 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
24140 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
24150 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
24160 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
24170 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
24180 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
24190 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
241a0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
241b0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
241c0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
241d0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
241e0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
241f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24200 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
24210 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
24220 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
24230 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
24240 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
24250 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
24260 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
24270 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
24280 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
24290 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
242a0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
242b0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
242c0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
242d0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
242e0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
242f0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
24300 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
24310 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
24320 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
24330 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
24340 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
24350 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
24360 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
24370 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
24380 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
24390 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
243a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
243b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
243c0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
243d0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
243e0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
243f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
24400 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
24410 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
24420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
24430 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
24440 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
24450 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
24460 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
24470 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
24480 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
24490 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
244a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
244b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
244c0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
244d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
244e0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
244f0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
24500 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
24510 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
24520 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
24530 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
24540 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
24550 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
24560 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
24570 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
24580 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
24590 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
245a0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
245b0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
245c0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
245d0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
245e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
245f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24600 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24610 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24620 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
24630 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
24640 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
24650 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
24660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24670 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
24680 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
24690 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
246a0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
246b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
246c0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
246d0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
246e0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
246f0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
24700 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
24710 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
24720 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
24730 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
24740 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
24750 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
24760 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
24770 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
24780 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
24790 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
247a0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
247b0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
247c0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
247d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
247e0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
247f0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
24800 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
24810 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
24820 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
24830 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
24840 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
24850 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
24860 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
24870 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
24880 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
24890 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
248a0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
248b0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
248c0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
248d0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
248e0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
248f0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
24900 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
24910 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
24920 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
24930 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
24940 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
24950 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
24960 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
24970 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
24980 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
24990 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
249a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
249b0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
249c0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
249d0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
249e0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
249f0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
24a00 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
24a10 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
24a20 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
24a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
24a40 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
24a50 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
24a60 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
24a70 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
24a80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
24a90 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
24aa0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
24ab0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
24ac0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
24ad0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
24ae0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
24af0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
24b00 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
24b10 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
24b20 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
24b30 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
24b40 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
24b50 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
24b60 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
24b70 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
24b80 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
24b90 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
24ba0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
24bb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
24bc0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
24bd0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
24be0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
24bf0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
24c00 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
24c10 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
24c20 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
24c30 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
24c40 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
24c50 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
24c60 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
24c70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
24c80 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
24c90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
24ca0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
24cb0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
24cc0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
24cd0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
24ce0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
24cf0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
24d00 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
24d10 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
24d20 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
24d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24d40 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
24d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24d60 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
24d70 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
24d80 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
24d90 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
24da0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
24db0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
24dc0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
24dd0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
24de0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
24df0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
24e00 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
24e10 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
24e20 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
24e30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24e40 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
24e50 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
24e60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
24e70 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
24e80 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
24e90 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
24ea0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
24eb0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
24ec0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
24ed0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
24ee0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
24ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24f00 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
24f10 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
24f20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
24f30 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
24f40 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
24f50 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
24f60 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
24f70 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
24f80 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
24f90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
24fa0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
24fb0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
24fc0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
24fd0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
24fe0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
24ff0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
25000 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
25010 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
25020 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
25030 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
25040 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
25050 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
25060 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25070 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
25080 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
25090 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
250a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
250b0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
250c0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
250d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
250e0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
250f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25100 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
25110 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
25120 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
25130 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
25140 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
25150 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
25160 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
25170 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
25180 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
25190 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
251a0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
251b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
251c0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
251d0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
251e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
251f0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
25200 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
25210 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
25220 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
25230 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
25240 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
25250 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
25260 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
25270 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
25280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
25290 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
252a0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
252b0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
252c0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
252d0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
252e0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
252f0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
25300 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
25310 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
25320 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
25330 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25340 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
25350 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
25360 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
25370 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
25380 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
25390 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
253a0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
253b0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
253c0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
253d0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
253e0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
253f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25400 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
25410 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
25420 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
25430 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
25440 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25450 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
25460 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
25470 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
25480 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
25490 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
254a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
254b0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
254c0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
254d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
254e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
254f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
25500 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
25510 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
25520 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
25530 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
25540 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
25550 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25560 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
25570 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25580 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
25590 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
255a0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
255b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
255c0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
255d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
255e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
255f0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
25600 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
25610 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
25620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25630 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
25640 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25650 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
25660 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
25670 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
25680 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
25690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
256a0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
256b0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
256c0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
256d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
256e0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
256f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
25700 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
25710 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
25720 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
25730 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
25740 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
25760 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
25770 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
25780 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
25790 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
257a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
257b0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
257c0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
257d0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
257e0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
257f0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
25800 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
25810 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
25820 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
25830 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
25840 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
25850 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
25860 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
25870 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
25880 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
25890 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
258a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
258b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
258c0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
258d0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
258e0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
258f0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
25900 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
25910 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
25920 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
25930 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
25940 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
25950 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
25960 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
25970 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
25980 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
25990 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
259a0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
259b0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
259c0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
259d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
259e0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
259f0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
25a00 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25a10 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
25a20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
25a30 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
25a40 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
25a50 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
25a60 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
25a70 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
25a80 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
25a90 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
25aa0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
25ab0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
25ac0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
25ad0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
25ae0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
25af0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
25b00 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
25b10 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
25b20 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
25b30 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
25b40 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
25b50 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
25b60 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
25b70 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
25b80 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
25b90 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
25ba0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
25bb0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25bc0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
25bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25be0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
25bf0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
25c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
25c10 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
25c20 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
25c30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25c40 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
25c50 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
25c60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
25c70 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
25c80 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
25c90 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
25ca0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
25cb0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
25cc0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
25cd0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
25ce0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
25cf0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
25d00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25d10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
25d20 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
25d30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
25d40 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
25d50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
25d60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
25d70 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
25d80 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
25d90 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
25da0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
25db0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
25dc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
25dd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
25de0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
25df0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
25e00 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
25e10 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
25e20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25e30 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
25e40 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
25e50 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
25e60 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
25e70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25e80 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
25e90 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
25ea0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
25eb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
25ec0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
25ed0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25ee0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
25ef0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
25f00 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
25f10 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
25f20 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
25f30 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
25f40 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
25f50 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
25f60 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
25f70 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
25f80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25f90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
25fa0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
25fb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
25fc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
25fd0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
25fe0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
25ff0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
26000 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26010 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
26030 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
26040 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
26050 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
26060 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
26070 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
26080 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
26090 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
260a0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
260b0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
260c0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
260d0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
260e0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
260f0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
26100 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
26110 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
26120 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
26130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26140 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
26150 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
26160 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
26170 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
26180 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
26190 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
261a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
261b0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
261c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
261d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
261e0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
261f0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
26200 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26210 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
26220 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
26230 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
26240 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
26250 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
26260 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
26270 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
26280 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
26290 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
262a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
262b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
262c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
262d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
262e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
262f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
26300 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
26310 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
26320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
26330 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
26340 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
26350 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
26360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
26370 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
26380 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
26390 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
263a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
263b0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
263c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
263d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
263e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
263f0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
26400 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
26410 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26420 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
26430 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
26440 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
26450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26460 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
26470 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
26480 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
26490 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
264a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
264b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
264c0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
264d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
264e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
264f0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
26500 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
26510 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
26520 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
26530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26540 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
26550 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
26560 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
26570 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
26580 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
26590 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
265a0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
265b0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
265c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
265d0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
265e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
265f0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
26600 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
26610 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
26620 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
26630 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26640 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
26650 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
26660 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
26670 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26680 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
26690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
266a0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
266b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
266c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
266d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
266e0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
266f0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
26700 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
26710 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
26720 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
26730 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
26740 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
26750 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
26760 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
26770 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26780 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
26790 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
267a0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
267b0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
267c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
267d0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
267e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
267f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26800 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
26810 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26820 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
26830 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
26840 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
26850 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
26860 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
26870 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
26880 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
26890 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
268a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
268b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
268c0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
268d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
268e0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
268f0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
26900 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26910 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
26920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26930 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
26940 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
26950 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
26960 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
26970 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26980 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
26990 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
269a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
269b0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
269c0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
269d0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
269e0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
269f0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
26a00 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
26a10 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
26a20 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
26a30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
26a40 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
26a50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26a60 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
26a70 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26a80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26a90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26aa0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
26ab0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
26ac0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
26ad0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
26ae0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
26af0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
26b00 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
26b10 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
26b20 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
26b30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
26b40 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
26b50 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
26b60 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
26b70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
26b80 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
26b90 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
26ba0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
26bb0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
26bc0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
26bd0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
26be0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
26bf0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
26c00 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
26c10 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
26c20 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
26c30 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
26c40 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
26c50 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
26c60 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
26c70 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
26c80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26c90 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
26ca0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26cb0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
26cc0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
26cd0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
26ce0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26cf0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
26d00 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
26d10 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
26d20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
26d30 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
26d40 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
26d50 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
26d60 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
26d70 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
26d80 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
26d90 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
26da0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
26db0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
26dc0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
26dd0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
26de0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
26df0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
26e00 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
26e10 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
26e20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
26e30 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
26e40 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
26e50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26e60 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
26e70 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
26e80 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26e90 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
26ea0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
26eb0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
26ec0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
26ed0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
26ee0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
26ef0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
26f00 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26f10 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
26f20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
26f30 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
26f40 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
26f50 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
26f60 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
26f70 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
26f80 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
26f90 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
26fa0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26fb0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26fc0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26fd0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26fe0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
26ff0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
27000 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
27010 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
27020 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
27030 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
27040 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
27050 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
27060 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
27070 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
27080 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
27090 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
270a0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
270b0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
270c0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
270d0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
270e0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
270f0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
27100 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
27110 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
27120 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
27130 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
27140 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
27150 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
27160 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
27170 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
27180 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
27190 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
271a0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
271b0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
271c0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
271d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
271e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
271f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27200 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
27210 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27220 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
27230 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
27240 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
27250 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
27260 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
27270 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
27280 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
27290 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
272a0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
272b0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
272c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
272d0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
272e0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
272f0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
27300 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
27310 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
27320 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
27330 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
27340 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
27350 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
27360 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
27370 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
27380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27390 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
273a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
273b0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
273c0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
273d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
273e0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
273f0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
27400 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
27410 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
27420 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
27430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
27440 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
27450 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27460 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
27470 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
27480 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
27490 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
274a0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
274b0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
274c0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
274d0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
274e0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
274f0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
27500 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
27510 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
27520 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
27530 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27540 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
27550 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
27560 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
27570 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
27580 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
27590 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
275a0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
275b0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
275c0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
275d0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
275e0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
275f0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
27600 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
27610 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
27620 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
27630 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
27640 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
27650 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
27660 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
27670 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
27680 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
27690 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
276a0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
276b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
276c0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
276d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
276e0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
276f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27700 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
27710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27720 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
27730 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
27740 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
27750 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
27760 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
27770 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
27780 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
27790 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
277a0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
277b0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
277c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
277d0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
277e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
277f0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
27800 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
27810 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
27820 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
27830 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27840 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
27850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27860 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
27870 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
27880 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
27890 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
278a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
278b0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
278c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
278d0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
278e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
278f0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
27900 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
27910 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
27920 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
27930 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
27940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27950 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
27960 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
27970 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
27980 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
27990 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
279a0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
279b0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
279c0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
279d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
279e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
279f0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
27a00 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
27a10 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
27a20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
27a30 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
27a40 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
27a50 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
27a60 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
27a70 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
27a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27a90 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
27ab0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
27ac0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
27ad0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
27ae0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
27af0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
27b00 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
27b10 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
27b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
27b30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
27b40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
27b50 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
27b60 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
27b70 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
27b80 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
27b90 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
27ba0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
27bb0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
27bc0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
27bd0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
27be0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
27bf0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
27c00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
27c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27c20 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
27c30 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27c40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27c60 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
27c70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27c80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27ca0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
27cb0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27cc0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
27cd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27ce0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
27cf0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27d00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27d10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27d20 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
27d30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
27d40 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
27d50 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
27d60 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
27d70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
27d80 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
27d90 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
27da0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27db0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
27dc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27dd0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
27de0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27df0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27e10 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
27e20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27e30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
27e40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27e50 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
27e60 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
27e70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27e80 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
27e90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
27ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27eb0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
27ec0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
27ed0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
27ee0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27ef0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
27f00 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
27f10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27f20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
27f30 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27f40 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
27f50 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
27f60 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
27f70 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68  s or.** or if th
27f80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
27f90 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
27fa0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
27fb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
27fc0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
27fd0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
27fe0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
27ff0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
28000 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
28010 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
28020 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
28030 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
28040 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
28050 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
28060 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
28070 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
28080 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
28090 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
280a0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
280b0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
280c0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
280d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
280e0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
280f0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
28100 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
28110 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
28120 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
28130 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
28140 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
28150 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28160 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
28170 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
28180 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
28190 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
281a0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
281b0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
281c0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
281d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
281e0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
281f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
28200 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
28210 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
28220 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28230 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
28240 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
28250 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
28260 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
28270 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
28280 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
28290 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
282a0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
282b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
282c0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
282d0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
282e0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
282f0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
28300 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
28310 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
28320 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
28330 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
28340 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
28350 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
28360 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
28370 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
28380 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
28390 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
283a0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
283b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
283c0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
283d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
283e0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
283f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
28400 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
28410 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
28420 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
28430 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
28440 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
28450 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
28460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
28470 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
28480 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
28490 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
284a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
284b0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
284c0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
284d0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
284e0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
284f0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
28500 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
28510 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
28520 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
28530 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
28540 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
28550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28560 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
28570 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
28580 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
28590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
285a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
285b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
285c0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
285d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
285e0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
285f0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
28600 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
28610 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
28620 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
28630 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
28640 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
28650 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
28660 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
28670 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
28680 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
28690 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
286a0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
286b0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
286c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
286d0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
286e0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
286f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
28700 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
28710 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
28720 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
28730 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
28740 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
28750 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
28760 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
28770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28780 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
28790 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
287a0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
287b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
287c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
287d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
287e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
287f0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
28800 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
28810 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
28820 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
28830 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
28840 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
28850 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
28870 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
28880 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
288a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
288b0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
288c0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
288d0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
288e0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
288f0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
28900 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
28910 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
28920 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
28930 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
28940 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
28950 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
28960 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
28970 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
28980 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
28990 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
289a0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
289b0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
289c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
289d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
289e0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
289f0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
28a00 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
28a10 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
28a20 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
28a30 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
28a40 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
28a50 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
28a60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28a70 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
28a80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
28a90 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
28aa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
28ab0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
28ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
28ad0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
28ae0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28af0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
28b00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28b10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
28b20 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
28b30 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
28b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
28b50 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
28b60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
28b70 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
28b80 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
28b90 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
28ba0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
28bb0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
28bc0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
28bd0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
28be0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
28bf0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
28c00 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
28c10 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
28c20 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
28c30 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
28c40 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
28c50 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
28c60 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
28c70 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
28c80 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
28c90 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
28ca0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
28cb0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
28cc0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
28cd0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
28ce0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
28cf0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28d00 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
28d10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
28d20 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
28d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28d40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
28d50 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
28d60 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
28d70 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
28d80 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
28d90 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
28da0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
28db0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
28dc0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
28dd0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
28de0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
28df0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28e00 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
28e10 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
28e20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
28e30 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
28e40 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
28e50 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
28e60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
28e70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28e80 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
28e90 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
28ea0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
28eb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
28ec0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
28ed0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
28ee0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
28ef0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
28f00 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28f10 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
28f20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
28f30 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
28f40 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
28f50 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
28f60 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
28f70 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
28f80 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
28f90 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
28fa0 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
28fb0 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
28fc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28fd0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
28fe0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28ff0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
29000 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
29010 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
29020 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
29030 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
29040 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
29050 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
29060 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
29070 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
29080 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
29090 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
290a0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
290b0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
290c0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
290d0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
290e0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
290f0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
29100 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
29110 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
29120 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
29130 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
29140 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
29150 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
29160 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
29170 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
29180 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
29190 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
291a0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
291b0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
291c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
291d0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
291e0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
291f0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
29200 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
29210 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
29220 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
29230 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
29240 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
29250 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
29260 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
29270 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
29280 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
29290 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
292a0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
292b0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
292c0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
292d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
292e0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
292f0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
29300 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
29310 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
29320 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
29330 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
29340 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
29350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
29360 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
29370 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
29380 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
29390 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
293a0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
293b0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
293c0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
293d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
293e0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
293f0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
29400 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
29410 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
29420 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
29430 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
29440 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29450 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
29460 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
29470 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
29480 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
29490 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
294a0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
294b0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
294c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
294d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
294e0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
294f0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
29500 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
29510 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29520 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
29530 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
29540 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
29550 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
29560 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
29570 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
29580 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
29590 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
295a0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
295b0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
295c0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
295d0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
295e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
295f0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
29600 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29610 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
29620 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
29630 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
29640 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
29650 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
29660 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
29670 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
29680 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
29690 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
296a0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
296b0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
296c0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
296d0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
296e0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
296f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
29700 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
29710 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
29720 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
29730 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
29740 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
29750 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
29760 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
29770 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
29780 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
29790 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
297a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
297b0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
297c0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
297d0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
297e0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
297f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
29800 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
29810 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
29820 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
29830 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
29840 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
29850 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
29860 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
29870 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
29880 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
29890 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
298a0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
298b0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
298c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
298d0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
298e0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
298f0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
29900 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
29910 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
29920 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
29930 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
29940 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
29950 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
29960 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
29970 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
29980 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
29990 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
299a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
299b0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
299c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
299d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
299e0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
299f0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
29a00 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
29a10 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
29a20 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
29a30 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
29a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
29a50 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
29a60 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
29a70 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
29a80 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
29a90 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
29aa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29ab0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
29ac0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
29ad0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
29ae0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
29af0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
29b00 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
29b10 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
29b20 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
29b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29b40 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29b50 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
29b60 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
29b70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29b80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29b90 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
29ba0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29bb0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
29bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
29bd0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
29be0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
29bf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
29c00 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
29c10 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
29c20 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
29c30 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
29c40 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
29c50 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
29c60 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
29c70 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
29c80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
29c90 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
29ca0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
29cb0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
29cc0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
29cd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29ce0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
29cf0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
29d00 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
29d10 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
29d20 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
29d30 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
29d40 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
29d50 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
29d60 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
29d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
29d80 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
29d90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29da0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29db0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
29dc0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
29dd0 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
29de0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
29df0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
29e00 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
29e10 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
29e20 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
29e30 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
29e40 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
29e50 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
29e60 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
29e70 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
29e80 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
29e90 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
29ea0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
29eb0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
29ec0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29ed0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
29ee0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
29ef0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
29f00 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
29f10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29f20 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
29f30 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
29f40 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
29f50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29f60 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
29f70 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
29f80 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
29f90 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
29fa0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
29fb0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
29fc0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
29fd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
29fe0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
29ff0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2a000 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2a010 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2a020 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2a030 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2a040 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2a050 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2a060 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2a070 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2a080 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2a090 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2a0a0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2a0b0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2a0c0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2a0d0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2a0e0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2a0f0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2a100 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2a110 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2a120 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2a130 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2a140 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2a150 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2a160 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2a170 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2a180 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2a190 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2a1a0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2a1b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2a1c0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2a1d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2a1e0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2a1f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2a200 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
2a210 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2a220 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
2a230 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
2a240 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2a250 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2a260 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
2a270 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
2a280 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2a290 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
2a2a0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2a2b0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
2a2c0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2a2d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
2a2e0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2a2f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2a300 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2a310 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2a320 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2a330 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2a340 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2a350 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2a360 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
2a370 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2a380 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2a390 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2a3a0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2a3b0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2a3c0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2a3d0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2a3e0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2a3f0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2a400 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2a410 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2a420 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2a430 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2a440 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2a450 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2a460 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a470 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2a480 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a490 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2a4a0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2a4b0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2a4c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a4d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2a4e0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
2a4f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2a500 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2a510 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2a520 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2a530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a540 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2a550 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2a560 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a570 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2a580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2a590 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2a5a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2a5b0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2a5c0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2a5d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a5e0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2a5f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2a600 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2a610 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2a620 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a630 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2a640 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2a650 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2a660 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a670 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2a680 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2a690 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2a6a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
2a6b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
2a6c0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
2a6d0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
2a6e0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a6f0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
2a700 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
2a710 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
2a720 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2a730 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a740 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
2a750 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
2a760 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
2a770 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
2a780 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
2a790 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a7a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2a7b0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2a7c0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
2a7d0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
2a7e0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
2a7f0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
2a800 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
2a810 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a820 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
2a830 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a840 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
2a850 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
2a860 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2a870 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2a880 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2a890 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
2a8a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2a8b0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
2a8c0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2a8d0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
2a8e0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
2a8f0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
2a900 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
2a910 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
2a920 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
2a930 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
2a940 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
2a950 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
2a960 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
2a970 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
2a980 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2a990 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
2a9a0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
2a9b0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
2a9c0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
2a9d0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
2a9e0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
2a9f0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
2aa00 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
2aa10 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
2aa20 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
2aa30 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2aa40 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
2aa50 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
2aa60 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
2aa70 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
2aa80 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
2aa90 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
2aaa0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
2aab0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
2aac0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2aad0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2aae0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2aaf0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2ab00 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2ab10 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2ab20 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2ab30 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2ab40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2ab50 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2ab60 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2ab70 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2ab80 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2ab90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2aba0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
2abb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2abc0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2abd0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2abe0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
2abf0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
2ac00 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
2ac10 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
2ac20 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
2ac30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2ac40 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2ac50 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2ac60 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2ac70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
2ac80 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2ac90 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2aca0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2acb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2acc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2acd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2ace0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2acf0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2ad00 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ad10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ad20 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2ad30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2ad40 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
2ad50 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2ad60 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2ad70 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ad80 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
2ad90 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2ada0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2adb0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2adc0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2add0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2ade0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
2adf0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2ae00 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ae10 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ae20 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2ae30 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ae40 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2ae50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ae60 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2ae70 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2ae80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2ae90 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
2aea0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2aeb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aec0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2aed0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2aee0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2aef0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2af00 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2af10 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2af20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2af30 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2af40 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2af50 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2af60 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2af70 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2af80 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2af90 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2afa0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2afb0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2afc0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2afd0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2afe0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2aff0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2b000 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2b010 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2b020 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2b030 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2b040 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2b050 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2b060 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2b070 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2b080 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2b090 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2b0a0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2b0b0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2b0c0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2b0d0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2b0e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2b0f0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2b100 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2b110 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2b120 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2b130 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2b140 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2b150 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2b160 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2b170 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2b180 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2b190 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2b1a0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2b1b0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2b1c0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2b1d0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2b1e0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2b1f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2b200 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2b210 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2b220 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2b230 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2b240 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2b250 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2b260 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2b270 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2b280 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2b290 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2b2a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b2b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2b2c0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2b2d0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2b2e0 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2b2f0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2b300 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2b310 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2b320 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2b330 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2b340 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2b350 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2b360 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2b370 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2b380 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2b390 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2b3a0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2b3b0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2b3c0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2b3d0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2b3e0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2b3f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2b400 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2b410 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2b420 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2b430 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2b440 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2b450 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2b460 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2b470 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2b480 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2b490 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2b4a0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2b4b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2b4c0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2b4d0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2b4e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2b4f0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2b500 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2b510 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2b520 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2b530 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2b540 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2b550 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2b560 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2b570 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2b580 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2b590 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2b5a0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2b5b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b5c0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2b5d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2b5e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2b5f0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2b600 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2b610 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2b620 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
2b630 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2b640 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2b650 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2b660 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2b670 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2b680 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
2b690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b6a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2b6b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b6c0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2b6d0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2b6e0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2b6f0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2b700 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2b710 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2b720 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b730 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2b740 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b750 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2b760 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2b770 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2b780 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b790 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2b7a0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2b7b0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2b7c0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2b7d0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2b7e0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2b7f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b800 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2b810 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
2b820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
2b830 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
2b840 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2b850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2b860 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2b870 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
2b880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b890 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2b8a0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2b8b0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2b8c0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2b8d0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2b8e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2b8f0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2b900 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2b910 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b920 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2b930 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b940 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2b950 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2b960 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2b970 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2b980 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2b990 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
2b9a0 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
2b9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2b9c0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2b9d0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2b9e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2b9f0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2ba00 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2ba10 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2ba20 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2ba30 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2ba40 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2ba50 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2ba60 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2ba70 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2ba80 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2ba90 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2baa0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2bab0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2bac0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2bad0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2bae0 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2baf0 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2bb00 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2bb10 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2bb20 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2bb30 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2bb40 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2bb50 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2bb60 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2bb70 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2bb80 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2bb90 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2bba0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2bbb0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2bbc0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2bbd0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2bbe0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2bbf0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2bc00 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2bc10 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2bc20 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2bc30 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2bc40 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2bc50 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2bc60 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2bc70 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2bc80 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2bc90 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2bca0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2bcb0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2bcc0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2bcd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bce0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2bcf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bd00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2bd10 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2bd20 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2bd30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2bd40 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2bd50 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2bd60 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2bd70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bd80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bd90 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2bda0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2bdb0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2bdc0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2bdd0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2bde0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2bdf0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2be00 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2be10 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2be20 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2be30 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2be40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2be50 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2be60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2be70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2be80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2be90 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2bea0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2beb0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2bec0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2bed0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2bee0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2bef0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2bf00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2bf10 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2bf20 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2bf30 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2bf40 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2bf50 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2bf60 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2bf70 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2bf80 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2bf90 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2bfa0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2bfb0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2bfc0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2bfd0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2bfe0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2bff0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2c000 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2c010 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2c020 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2c030 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2c040 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2c050 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2c060 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2c070 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2c080 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2c090 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2c0a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2c0b0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2c0c0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2c0d0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2c0e0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2c0f0 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2c100 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2c110 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2c120 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2c130 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2c140 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2c150 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2c160 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2c170 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2c180 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2c190 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2c1a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2c1b0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2c1c0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2c1d0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2c1e0 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2c1f0 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2c200 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c210 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2c220 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2c230 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2c240 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c250 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2c260 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2c270 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2c280 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2c290 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
2c2a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
2c2b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2c2c0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2c2d0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
2c2e0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
2c2f0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
2c300 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
2c310 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
2c320 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
2c330 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
2c340 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
2c350 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
2c360 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
2c370 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2c380 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
2c390 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
2c3a0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
2c3b0 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
2c3c0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2c3d0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2c3e0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2c3f0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2c400 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2c410 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2c420 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2c430 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2c440 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2c450 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
2c460 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2c470 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2c480 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2c490 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2c4a0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2c4b0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2c4c0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2c4d0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2c4e0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2c4f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2c500 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2c510 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2c520 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2c530 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2c540 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2c550 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2c560 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2c570 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2c580 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2c590 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2c5a0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2c5b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2c5c0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2c5d0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2c5e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c5f0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2c600 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2c610 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2c620 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2c630 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2c640 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2c650 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2c660 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
2c670 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
2c680 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
2c690 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
2c6a0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
2c6b0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
2c6c0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
2c6d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c6e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c6f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c700 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
2c710 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2c720 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
2c730 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
2c740 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
2c750 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
2c760 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
2c770 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
2c780 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
2c790 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2c7a0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2c7b0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2c7c0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
2c7d0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
2c7e0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2c7f0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2c800 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2c810 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c820 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2c830 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2c840 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2c850 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c860 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2c870 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2c880 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2c890 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2c8a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c8b0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2c8c0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2c8d0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2c8e0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2c8f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c900 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2c910 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2c920 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2c930 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2c940 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c950 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2c960 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2c970 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2c980 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2c990 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2c9a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2c9b0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2c9c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c9d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
2c9e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2c9f0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2ca00 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2ca10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ca20 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
2ca30 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
2ca40 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
2ca50 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
2ca60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ca70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ca80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2ca90 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2caa0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
2cab0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
2cac0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2cad0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
2cae0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
2caf0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
2cb00 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
2cb10 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
2cb20 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
2cb30 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2cb40 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2cb50 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
2cb60 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
2cb70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
2cb80 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
2cb90 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
2cba0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
2cbb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2cbc0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
2cbd0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
2cbe0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2cbf0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2cc00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2cc10 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
2cc20 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
2cc30 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
2cc40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2cc50 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2cc60 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2cc70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2cc80 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
2cc90 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2cca0 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
2ccb0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
2ccc0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
2ccd0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2cce0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2ccf0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2cd00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2cd10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2cd20 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2cd30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2cd40 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2cd50 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2cd60 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
2cd70 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2cd80 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
2cd90 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
2cda0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2cdb0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
2cdc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cdd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2cde0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2cdf0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2ce00 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
2ce10 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2ce20 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2ce30 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2ce40 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2ce50 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2ce60 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2ce70 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2ce80 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2ce90 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2cea0 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
2ceb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2cec0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2ced0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2cee0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2cef0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2cf00 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2cf10 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2cf20 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
2cf30 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
2cf40 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
2cf50 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
2cf60 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2cf70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cf80 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2cf90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2cfa0 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
2cfb0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
2cfc0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
2cfd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2cfe0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
2cff0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2d000 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2d010 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2d020 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
2d030 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
2d040 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
2d050 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2d060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2d070 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
2d080 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2d090 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2d0a0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2d0b0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
2d0c0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
2d0d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d0e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
2d0f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2d100 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2d110 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2d120 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d130 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2d140 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
2d150 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2d160 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2d170 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2d180 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d190 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
2d1a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2d1b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2d1c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2d1d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2d1e0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
2d1f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2d200 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2d210 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2d220 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2d230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2d240 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2d250 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2d260 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2d270 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d280 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2d290 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
2d2a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2d2b0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2d2c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2d2d0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
2d2e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2d2f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2d300 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2d310 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2d320 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2d330 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2d340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d350 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2d360 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2d370 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2d380 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2d390 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2d3a0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2d3b0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2d3c0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2d3d0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2d3e0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
2d3f0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2d400 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2d410 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2d420 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2d430 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2d440 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2d450 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
2d460 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2d470 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2d480 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2d490 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2d4a0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2d4b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
2d4c0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
2d4d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
2d4e0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2d4f0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2d500 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2d510 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2d520 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2d530 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2d540 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
2d550 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
2d560 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
2d570 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
2d580 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
2d590 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
2d5a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2d5b0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
2d5c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d5d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
2d5e0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2d5f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2d600 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2d610 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2d620 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2d630 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2d640 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
2d650 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2d660 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
2d670 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
2d680 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2d690 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2d6a0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
2d6b0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2d6c0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2d6d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2d6e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d6f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d700 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2d710 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
2d720 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2d730 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2d740 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
2d750 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
2d760 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
2d770 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2d780 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
2d790 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
2d7a0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
2d7b0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
2d7c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2d7d0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
2d7e0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
2d7f0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
2d800 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
2d810 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2d820 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2d830 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2d840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d850 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2d860 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2d870 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2d880 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2d890 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2d8a0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2d8b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2d8c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2d8d0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2d8e0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2d8f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2d900 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2d910 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2d920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2d930 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2d940 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2d950 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2d960 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2d970 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
2d980 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
2d990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d9a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
2d9b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
2d9c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
2d9d0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2d9e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2d9f0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2da00 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2da10 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2da20 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
2da30 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
2da40 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
2da50 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
2da60 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
2da70 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
2da80 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2da90 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
2daa0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
2dab0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dac0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2dad0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2dae0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2daf0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2db00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2db10 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2db20 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2db30 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2db40 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2db50 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2db60 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2db70 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2db80 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2db90 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2dba0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
2dbb0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
2dbc0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2dbd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dbe0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
2dbf0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
2dc00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2dc10 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
2dc20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2dc30 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
2dc40 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
2dc50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2dc60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2dc70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2dc80 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2dc90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
2dca0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2dcb0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2dcc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2dcd0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
2dce0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2dcf0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2dd00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2dd10 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
2dd20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2dd30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2dd40 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
2dd50 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2dd60 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
2dd70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
2dd80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2dd90 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2dda0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
2ddb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
2ddc0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2ddd0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2dde0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
2ddf0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
2de00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2de10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2de20 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
2de30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
2de40 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
2de50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2de60 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
2de70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2de80 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
2de90 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2dea0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
2deb0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2dec0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
2ded0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2dee0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
2def0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2df00 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2df10 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2df20 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2df30 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2df40 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2df50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2df60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2df70 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2df80 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2df90 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2dfa0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
2dfb0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2dfc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2dfd0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2dfe0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2dff0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
2e000 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2e010 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2e020 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2e030 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2e040 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2e050 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2e060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2e070 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
2e080 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
2e090 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2e0a0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
2e0b0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
2e0c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e0d0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2e0e0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
2e0f0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
2e100 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
2e110 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2e120 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
2e130 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
2e140 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
2e150 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2e160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e170 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2e180 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2e190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2e1a0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
2e1b0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
2e1c0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2e1d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e1e0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2e1f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e200 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2e210 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2e220 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
2e230 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
2e240 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e250 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
2e260 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
2e270 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
2e280 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
2e290 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
2e2a0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
2e2b0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
2e2c0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
2e2d0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2e2e0 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
2e2f0 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
2e300 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
2e310 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
2e320 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
2e330 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
2e340 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
2e350 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2e360 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2e370 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
2e380 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2e390 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
2e3a0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
2e3b0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
2e3c0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
2e3d0 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
2e3e0 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
2e3f0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2e400 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
2e410 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
2e420 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
2e430 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
2e440 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
2e450 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
2e460 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
2e470 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
2e480 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
2e490 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
2e4a0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2e4b0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
2e4c0 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
2e4d0 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
2e4e0 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
2e4f0 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
2e500 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
2e510 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
2e520 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2e530 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
2e540 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
2e550 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
2e560 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2e570 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2e580 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
2e590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2e5a0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
2e5b0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
2e5c0 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
2e5d0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
2e5e0 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
2e5f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
2e600 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
2e610 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
2e620 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
2e630 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
2e640 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
2e650 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
2e660 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
2e670 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2e680 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2e690 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
2e6a0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
2e6b0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
2e6c0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
2e6d0 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
2e6e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
2e6f0 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
2e700 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
2e710 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
2e720 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2e730 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
2e740 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
2e750 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
2e760 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
2e770 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e780 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
2e790 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
2e7a0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
2e7b0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
2e7c0 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
2e7d0 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
2e7e0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
2e7f0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2e800 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
2e810 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
2e820 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e830 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
2e840 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
2e850 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
2e860 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
2e870 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2e880 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2e890 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
2e8a0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2e8b0 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
2e8c0 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
2e8d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e8e0 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
2e8f0 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
2e900 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
2e910 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
2e920 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
2e930 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
2e940 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
2e950 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
2e960 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
2e970 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
2e980 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
2e990 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
2e9a0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
2e9b0 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
2e9c0 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
2e9d0 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
2e9e0 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
2e9f0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
2ea00 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
2ea10 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
2ea20 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
2ea30 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
2ea40 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
2ea50 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
2ea60 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
2ea70 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
2ea80 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
2ea90 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
2eaa0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
2eab0 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
2eac0 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
2ead0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
2eae0 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
2eaf0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
2eb00 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
2eb10 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2eb20 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
2eb30 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
2eb40 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
2eb50 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2eb60 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
2eb70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2eb80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2eb90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2eba0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2ebb0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2ebc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2ebd0 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
2ebe0 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
2ebf0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
2ec00 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
2ec10 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
2ec20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2ec30 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
2ec40 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
2ec50 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
2ec60 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
2ec70 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2ec80 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
2ec90 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2eca0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
2ecb0 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
2ecc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ecd0 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
2ece0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2ecf0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
2ed00 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
2ed10 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
2ed20 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
2ed30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2ed40 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2ed50 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
2ed60 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
2ed70 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
2ed80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ed90 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
2eda0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
2edb0 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
2edc0 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
2edd0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
2ede0 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
2edf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ee00 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
2ee10 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
2ee20 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
2ee30 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
2ee40 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
2ee50 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
2ee60 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
2ee70 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
2ee80 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
2ee90 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
2eea0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
2eeb0 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
2eec0 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
2eed0 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
2eee0 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2eef0 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
2ef00 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
2ef10 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2ef20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2ef30 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2ef40 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2ef50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2ef60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ef70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2ef80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2ef90 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2efa0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2efb0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2efc0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2efd0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2efe0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
2eff0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f000 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2f010 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2f020 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2f030 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2f040 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2f050 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
2f060 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2f070 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f080 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f090 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
2f0a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2f0b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f0c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2f0d0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2f0e0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2f0f0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2f100 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2f110 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
2f120 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2f130 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2f140 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2f150 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2f160 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
2f170 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
2f180 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
2f190 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
2f1a0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
2f1b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
2f1c0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
2f1d0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
2f1e0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
2f1f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
2f200 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
2f210 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
2f220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f230 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2f240 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
2f250 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
2f260 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
2f270 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
2f280 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2f290 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2f2a0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
2f2b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2f2c0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
2f2d0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
2f2e0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
2f2f0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2f300 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
2f310 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
2f320 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
2f330 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f340 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
2f350 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
2f360 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
2f370 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
2f380 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2f390 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
2f3a0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
2f3b0 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
2f3c0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
2f3d0 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
2f3e0 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
2f3f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2f400 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
2f410 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
2f420 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
2f430 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2f440 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
2f450 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2f460 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2f470 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2f480 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
2f490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2f4a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2f4b0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
2f4c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2f4d0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
2f4e0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2f4f0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
2f500 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2f510 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
2f520 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
2f530 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
2f540 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2f550 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2f560 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
2f570 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f580 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
2f590 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
2f5a0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
2f5b0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2f5c0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
2f5d0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
2f5e0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
2f5f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2f600 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2f610 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
2f620 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2f630 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
2f640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2f650 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
2f660 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f670 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2f680 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2f690 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2f6a0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2f6b0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2f6c0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2f6d0 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
2f6e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f6f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2f700 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2f710 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2f720 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2f730 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2f740 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
2f750 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
2f760 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
2f770 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
2f780 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
2f790 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
2f7a0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
2f7b0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
2f7c0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
2f7d0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
2f7e0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2f7f0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2f800 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2f810 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2f820 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2f830 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f840 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2f850 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2f860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f870 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2f880 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2f890 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2f8a0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2f8b0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2f8c0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2f8d0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2f8e0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2f8f0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2f900 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2f910 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2f920 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2f930 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2f940 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2f950 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2f960 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2f970 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2f980 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2f990 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2f9a0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2f9b0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2f9c0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
2f9d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2f9e0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
2f9f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2fa00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2fa10 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2fa20 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2fa30 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2fa40 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
2fa50 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2fa60 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2fa70 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2fa80 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
2fa90 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
2faa0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
2fab0 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
2fac0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
2fad0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
2fae0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2faf0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2fb00 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2fb10 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2fb20 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2fb30 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2fb40 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2fb50 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2fb60 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2fb70 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2fb80 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2fb90 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2fba0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2fbb0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2fbc0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
2fbd0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2fbe0 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
2fbf0 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
2fc00 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
2fc10 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
2fc20 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
2fc30 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2fc40 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
2fc50 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
2fc60 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
2fc70 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2fc80 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2fc90 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2fca0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2fcb0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2fcc0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2fcd0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2fce0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2fcf0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2fd00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
2fd10 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2fd20 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2fd30 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2fd40 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
2fd50 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2fd60 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2fd70 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2fd80 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
2fd90 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
2fda0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2fdb0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2fdc0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2fdd0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2fde0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2fdf0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2fe00 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2fe10 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2fe20 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2fe30 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2fe40 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2fe50 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2fe60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
2fe70 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
2fe80 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
2fe90 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
2fea0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
2feb0 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
2fec0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
2fed0 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
2fee0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2fef0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
2ff00 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
2ff10 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
2ff20 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
2ff30 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
2ff40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ff50 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2ff60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ff70 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
2ff80 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
2ff90 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
2ffa0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
2ffb0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2ffc0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2ffd0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2ffe0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2fff0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
30000 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
30010 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
30020 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
30030 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
30040 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
30050 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
30060 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
30070 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
30080 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
30090 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
300a0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
300b0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
300c0 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
300d0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
300e0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
300f0 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
30100 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
30110 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
30120 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
30130 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
30140 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
30150 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
30160 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
30170 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
30180 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
30190 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
301a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
301b0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
301c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
301d0 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
301e0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
301f0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
30200 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
30210 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
30220 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
30230 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
30240 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
30250 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
30260 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
30270 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
30280 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
30290 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
302a0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
302b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
302c0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
302d0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
302e0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
302f0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
30300 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
30310 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
30320 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
30330 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
30340 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
30350 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
30360 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
30370 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
30380 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
30390 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
303a0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
303b0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
303c0 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
303d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
303e0 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
303f0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
30400 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
30410 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
30420 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
30430 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
30440 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
30450 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
30460 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
30470 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
30480 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
30490 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
304a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
304b0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
304c0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
304d0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
304e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
304f0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
30500 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  /.SQLITE_API SQL
30510 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
30520 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
30530 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
30540 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
30550 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
30560 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
30570 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
30580 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
30590 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
305a0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
305b0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
305c0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
305d0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
305e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
305f0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
30600 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
30610 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
30620 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
30630 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
30640 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
30650 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
30660 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
30670 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
30680 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
30690 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
306a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
306b0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
306c0 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
306d0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
306e0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
306f0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
30700 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
30710 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
30720 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
30730 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
30740 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
30750 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
30760 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
30770 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
30780 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
30790 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
307a0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
307b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
307c0 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
307d0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
307e0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
307f0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
30800 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
30810 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
30820 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
30830 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
30840 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
30850 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
30860 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
30870 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
30880 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
30890 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
308a0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
308b0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
308c0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
308d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
308e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
308f0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
30900 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
30910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30920 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
30930 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
30940 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30960 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
30970 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30980 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30990 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
309a0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
309b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
309c0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
309d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
309e0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
309f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30a00 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
30a10 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
30a20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
30a30 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
30a40 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
30a50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
30a60 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
30a70 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
30a80 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
30a90 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
30aa0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
30ab0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
30ac0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
30ad0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
30ae0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
30af0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
30b00 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
30b10 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
30b20 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
30b30 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
30b40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30b50 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
30b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30b70 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
30b80 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
30b90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
30ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
30bb0 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
30bc0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
30bd0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
30be0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
30bf0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
30c00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
30c10 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30c20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
30c30 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
30c40 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
30c50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
30c60 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
30c70 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
30c80 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
30c90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
30ca0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30cb0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
30cc0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
30cd0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
30ce0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
30cf0 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
30d00 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30d10 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
30d20 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
30d30 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
30d40 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ter..*/.SQLITE_A
30d50 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  PI sqlite3_stmt 
30d60 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
30d70 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
30d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
30d90 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
30da0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
30db0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
30dc0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
30dd0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
30de0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30df0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
30e00 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
30e10 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
30e20 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
30e30 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
30e40 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
30e50 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
30e60 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
30e70 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
30e80 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
30e90 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
30ea0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
30eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30ec0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
30ed0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30ee0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
30ef0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
30f00 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
30f10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
30f20 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
30f30 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
30f40 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
30f50 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
30f60 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
30f70 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
30f80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
30f90 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
30fa0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
30fb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30fc0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
30fd0 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
30fe0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
30ff0 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
31000 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
31010 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
31020 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
31030 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
31040 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
31050 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
31060 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
31070 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
31080 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31090 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
310a0 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
310b0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
310c0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
310d0 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
310e0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
310f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
31100 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
31110 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
31120 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
31130 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
31140 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
31150 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
31160 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
31170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
31180 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  back implementat
31190 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
311a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
311b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
311c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
311d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
311e0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
311f0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
31200 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
31210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31220 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
31230 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
31240 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
31250 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
31260 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
31270 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
31280 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f   commit.** or ro
31290 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74  llback hook in t
312a0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
312b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
312c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
312d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
312e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
312f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
31300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31310 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
31320 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
31330 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
31340 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
31350 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
31360 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
31370 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
31380 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
31390 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
313a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
313b0 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
313c0 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
313d0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
313e0 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
313f0 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
31400 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
31410 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
31420 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
31430 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
31440 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
31450 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
31460 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
31470 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
31480 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
31490 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
314a0 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
314b0 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
314c0 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
314d0 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
314e0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
314f0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
31500 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
31510 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
31520 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
31530 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
31540 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
31550 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
31560 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
31570 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
31580 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
31590 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
315a0 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
315b0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
315c0 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
315d0 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
315e0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
315f0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
31600 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
31610 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
31620 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
31630 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
31640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
31650 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
31660 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rface..*/.SQLITE
31670 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
31680 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
31690 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
316a0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
316b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
316c0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
316d0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
316e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
316f0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
31700 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
31710 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
31720 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
31730 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31740 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
31750 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
31760 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
31770 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
31780 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31790 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
317a0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
317b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
317c0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
317d0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
317e0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
317f0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
31800 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
31810 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
31820 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
31830 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
31840 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
31850 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
31860 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
31870 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
31880 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
31890 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
318a0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
318b0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
318c0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
318d0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
318e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
318f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
31900 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31910 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
31920 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
31930 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
31940 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
31950 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
31960 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
31970 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
31980 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
31990 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
319a0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
319b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
319c0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
319d0 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
319e0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
319f0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
31a00 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
31a10 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
31a20 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
31a30 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
31a40 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
31a50 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
31a60 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
31a70 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
31a80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31a90 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
31aa0 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
31ab0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
31ac0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
31ad0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
31ae0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
31af0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
31b00 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
31b10 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31b20 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
31b30 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
31b40 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
31b50 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
31b60 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
31b70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
31b80 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
31b90 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
31ba0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
31bb0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31bc0 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
31bd0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
31be0 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
31bf0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
31c00 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
31c10 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
31c20 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
31c30 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
31c40 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
31c50 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
31c60 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
31c70 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
31c80 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
31c90 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
31ca0 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
31cb0 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
31cc0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
31cd0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
31ce0 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
31cf0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
31d00 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
31d10 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
31d20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31d30 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
31d40 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
31d50 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
31d60 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
31d70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31d80 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
31d90 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
31da0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
31db0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
31dc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31dd0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
31de0 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
31df0 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
31e00 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
31e10 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
31e20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
31e30 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
31e40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
31e50 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
31e60 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
31e70 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
31e80 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
31e90 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
31ea0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
31eb0 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
31ec0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
31ed0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
31ee0 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
31ef0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
31f00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
31f10 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
31f20 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
31f30 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
31f40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
31f50 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
31f60 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
31f70 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
31f80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51  nterfaces..*/.SQ
31f90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
31fa0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31fb0 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
31fc0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
31fd0 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
31fe0 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
31ff0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
32000 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
32010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
32020 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
32030 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
32040 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
32050 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
32060 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
32070 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
32080 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
32090 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
320a0 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
320b0 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
320c0 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
320d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
320e0 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
320f0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
32100 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
32110 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
32120 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
32130 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
32140 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
32150 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
32160 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
32170 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
32180 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
32190 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
321a0 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
321b0 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
321c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
321d0 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
321e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
321f0 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
32200 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
32210 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
32220 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
32230 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
32240 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
32250 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
32260 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
32270 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
32280 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
32290 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
322a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
322b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
322c0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
322d0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
322e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
322f0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
32300 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
32310 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
32320 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
32330 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
32340 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
32350 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
32360 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
32370 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
32380 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
32390 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
323a0 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
323b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
323c0 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
323d0 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
323e0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
323f0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
32400 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
32410 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
32420 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
32430 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
32440 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
32450 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
32460 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
32470 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
32480 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
32490 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
324a0 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c  che Mode].*/.SQL
324b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
324c0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
324d0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
324e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
324f0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
32500 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
32510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32520 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
32530 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
32540 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
32550 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
32560 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
32570 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
32580 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
32590 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
325a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
325b0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
325c0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
325d0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
325e0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
325f0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
32600 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
32610 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
32620 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
32630 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
32640 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32650 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
32660 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
32670 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
32680 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
32690 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
326a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
326b0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
326c0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
326d0 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
326e0 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
326f0 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
32700 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
32710 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
32720 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  EMENT]..*/.SQLIT
32730 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32740 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32750 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
32760 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
32770 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
32780 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
32790 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
327a0 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72  _limit64() inter
327b0 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72  face sets and/or
327c0 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20   queries the.** 
327d0 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68  soft limit on th
327e0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
327f0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
32800 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
32810 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c   SQLite..** ^SQL
32820 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b  ite strives to k
32830 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20  eep heap memory 
32840 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f  utilization belo
32850 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a  w the soft heap.
32860 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75  ** limit by redu
32870 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20  cing the number 
32880 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e  of pages held in
32890 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a   the page cache.
328a0 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72  ** as heap memor
328b0 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61 63  y usages approac
328c0 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a  hes the limit..*
328d0 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70  * ^The soft heap
328e0 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22   limit is "soft"
328f0 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74 68   because even th
32900 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72 69  ough SQLite stri
32910 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62  ves to stay.** b
32920 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20  elow the limit, 
32930 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74  it will exceed t
32940 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20  he limit rather 
32950 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a  than generate.**
32960 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45   an [SQLITE_NOME
32970 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74  M] error.  In ot
32980 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
32990 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a  oft heap limit .
329a0 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  ** is advisory o
329b0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
329c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
329d0 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  m sqlite3_soft_h
329e0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73  eap_limit64() is
329f0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
32a00 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32a10 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65  mit prior to the
32a20 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20   call.  ^If the 
32a30 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65  argument N is ne
32a40 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e  gative.** then n
32a50 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65  o change is made
32a60 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61   to the soft hea
32a70 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c  p limit.  Hence,
32a80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
32a90 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74  size of the soft
32aa0 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20   heap limit can 
32ab0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  be determined by
32ac0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
32ad0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32ae0 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61 20  imit64() with a 
32af0 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e  negative argumen
32b00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
32b10 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a   argument N is z
32b20 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66  ero then the sof
32b30 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
32b40 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
32b50 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  ^(The soft heap 
32b60 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66  limit is not enf
32b70 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75 72  orced in the cur
32b80 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
32b90 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72  ion.** if one or
32ba0 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69   more of followi
32bb0 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72  ng conditions ar
32bc0 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e true:.**.** <u
32bd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73  l>.** <li> The s
32be0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32bf0 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  s set to zero..*
32c00 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63  * <li> Memory ac
32c10 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61  counting is disa
32c20 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d  bled using a com
32c30 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  bination of the.
32c40 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
32c50 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
32c60 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
32c70 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69  S],...) start-ti
32c80 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a  me option and.**
32c90 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54        the [SQLIT
32ca0 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
32cb0 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  TUS] compile-tim
32cc0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  e option..** <li
32cd0 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  > An alternative
32ce0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
32cf0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70  ementation is sp
32d00 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a  ecified using.**
32d10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32d20 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
32d30 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e  ONFIG_PCACHE],..
32d40 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  .)..** <li> The 
32d50 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63  page cache alloc
32d60 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77  ates from its ow
32d70 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75  n memory pool su
32d80 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62  pplied.**      b
32d90 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  y [sqlite3_confi
32da0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
32db0 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e  G_PAGECACHE],...
32dc0 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ) rather than.**
32dd0 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68        from the h
32de0 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  eap..** </ul>)^.
32df0 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20  **.** Beginning 
32e00 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
32e10 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73  ion 3.7.3, the s
32e20 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32e30 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65  s enforced.** re
32e40 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
32e50 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
32e60 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
32e70 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
32e80 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
32e90 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b   option is invok
32ea0 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54  ed.  With [SQLIT
32eb0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
32ec0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20  MANAGEMENT],.** 
32ed0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32ee0 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20  mit is enforced 
32ef0 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20  on every memory 
32f00 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74  allocation.  Wit
32f10 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hout.** [SQLITE_
32f20 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
32f30 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73  NAGEMENT], the s
32f40 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32f50 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a  s only enforced.
32f60 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ** when memory i
32f70 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74  s allocated by t
32f80 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20  he page cache.  
32f90 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73  Testing suggests
32fa0 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a   that because.**
32fb0 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20   the page cache 
32fc0 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61  is the predomina
32fd0 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69  te memory user i
32fe0 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a  n SQLite, most.*
32ff0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  * applications w
33000 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71  ill achieve adeq
33010 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c  uate soft heap l
33020 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74  imit enforcement
33030 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20   without.** the 
33040 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  use of [SQLITE_E
33050 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
33060 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
33070 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  The circumstance
33080 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51  s under which SQ
33090 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63  Lite will enforc
330a0 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  e the soft heap 
330b0 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61  limit may.** cha
330c0 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  nges in future r
330d0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
330e0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
330f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
33100 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
33110 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
33120 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
33130 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
33140 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
33150 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
33160 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
33170 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
33180 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
33190 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
331a0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
331b0 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
331c0 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
331d0 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
331e0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
331f0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
33200 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
33210 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
33220 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
33230 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
33240 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
33250 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
33260 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
33270 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
33280 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
33290 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
332a0 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
332b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
332c0 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
332d0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
332e0 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
332f0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
33300 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
33310 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
33320 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
33330 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
33340 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
33350 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
33360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33370 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
33380 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
33390 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
333a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
333b0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
333c0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
333d0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
333e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
333f0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
33400 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
33410 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
33420 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
33430 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
33440 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
33450 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
33460 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
33470 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
33480 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
33490 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
334a0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
334b0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
334c0 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
334d0 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
334e0 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
334f0 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
33500 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
33510 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
33520 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
33530 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
33540 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
33550 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
33560 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
33570 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
33580 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
33590 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
335a0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
335b0 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
335c0 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
335d0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
335e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
335f0 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
33600 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
33610 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
33620 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
33630 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
33640 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
33650 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
33660 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
33670 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
33680 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
33690 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
336a0 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
336b0 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
336c0 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
336d0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
336e0 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
336f0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
33700 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
33710 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
33720 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
33730 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
33740 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
33750 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
33760 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
33770 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
33780 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
33790 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
337a0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
337b0 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
337c0 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
337d0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
337e0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
337f0 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
33800 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
33810 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
33820 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
33830 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
33840 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
33850 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
33860 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
33870 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
33880 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
33890 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
338a0 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
338b0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
338c0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
338d0 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
338e0 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
338f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33900 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
33910 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
33920 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
33930 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
33940 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
33950 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
33960 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
33970 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
33980 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
33990 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
339a0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
339b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
339c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
339d0 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
339e0 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
339f0 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
33a00 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
33a10 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
33a20 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
33a30 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
33a40 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
33a50 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
33a60 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
33a70 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
33a80 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
33a90 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
33aa0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
33ab0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
33ac0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
33ad0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
33ae0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
33af0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
33b00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
33b10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
33b20 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
33b30 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
33b40 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
33b50 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
33b60 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
33b70 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
33b80 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
33b90 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
33ba0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
33bb0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
33bc0 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
33bd0 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
33be0 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
33bf0 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
33c00 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
33c10 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
33c20 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
33c30 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
33c40 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
33c50 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
33c60 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
33c70 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
33c80 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
33c90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33ca0 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
33cb0 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
33cc0 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
33cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
33ce0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
33cf0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
33d00 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
33d10 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
33d20 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
33d30 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
33d40 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
33d50 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c   defined..*/.SQL
33d60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33d70 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
33d80 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
33d90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33da0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
33db0 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
33dc0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33dd0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
33de0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
33df0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
33e00 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
33e10 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
33e20 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
33e30 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
33e40 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
33e50 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
33e60 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
33e70 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
33e80 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
33e90 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
33ea0 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
33eb0 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
33ec0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
33ed0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
33ee0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
33ef0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
33f00 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
33f10 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
33f20 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
33f30 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
33f40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
33f50 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
33f60 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
33f70 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
33f80 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
33f90 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
33fa0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
33fb0 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
33fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33fd0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
33fe0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  sion.**.** ^This
33ff0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
34000 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
34010 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
34020 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
34030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34040 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
34050 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
34060 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
34070 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78   an.** SQLite ex
34080 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
34090 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
340a0 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
340b0 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f  ** ^The entry po
340c0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a  int is zProc..**
340d0 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30   ^zProc may be 0
340e0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
340f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
34100 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64  entry point.** d
34110 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
34120 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
34130 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  it"..** ^The sql
34140 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
34150 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
34160 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
34170 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
34180 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
34190 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
341a0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
341b0 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
341c0 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
341d0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
341e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
341f0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
34200 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
34210 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
34220 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
34230 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61  with error messa
34240 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
34250 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61  n memory.** obta
34260 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
34270 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68  e3_malloc()]. Th
34280 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
34290 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65  on.** should fre
342a0 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
342b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
342c0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
342d0 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
342e0 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
342f0 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  led using.** [sq
34300 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
34310 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  d_extension()] p
34320 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
34330 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68  this API,.** oth
34340 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
34350 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
34360 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34370 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
34380 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74  sion() SQL funct
34390 69 6f 6e 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ion]..*/.SQLITE_
343a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
343b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
343c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
343d0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
343e0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
343f0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
34400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
34410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
34420 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
34430 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
34440 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
34450 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
34460 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
34470 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
34480 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
34490 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
344a0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
344b0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
344c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
344d0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
344e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
344f0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
34500 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
34510 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
34520 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
34530 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
34540 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
34550 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
34560 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
34570 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
34580 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
34590 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
345a0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
345b0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
345c0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
345d0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
345e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
345f0 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
34600 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
34610 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
34620 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
34630 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
34640 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
34650 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
34660 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
34670 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
34680 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
34690 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
346a0 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
346b0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
346c0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
346d0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
346e0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
346f0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
34700 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
34710 61 67 61 69 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  again..*/.SQLITE
34720 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34730 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34740 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
34750 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
34760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34770 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
34780 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
34790 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
347a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
347b0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
347c0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
347d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
347e0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
347f0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
34800 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
34810 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
34820 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
34830 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
34840 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
34850 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
34860 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
34870 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
34880 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
34890 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
348a0 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
348b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
348c0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
348d0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
348e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
348f0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
34900 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
34910 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
34920 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
34930 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
34940 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
34950 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
34960 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
34970 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
34980 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
34990 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
349a0 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
349b0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
349c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
349d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
349e0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
349f0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
34a00 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
34a10 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
34a20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
34a30 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
34a40 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
34a50 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
34a60 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
34a70 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
34a80 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
34a90 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
34aa0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
34ab0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
34ac0 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
34ad0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
34ae0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
34af0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
34b00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
34b10 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34b20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
34b30 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
34b40 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
34b50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
34b60 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
34b70 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
34b80 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
34b90 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
34ba0 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
34bb0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
34bc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
34bd0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
34be0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
34bf0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
34c00 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
34c10 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
34c20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
34c30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
34c40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
34c50 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34c60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
34c70 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
34c80 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
34c90 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
34ca0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
34cb0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
34cc0 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
34cd0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
34ce0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
34cf0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
34d00 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
34d10 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
34d20 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
34d30 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
34d40 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
34d50 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
34d60 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
34d70 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
34d80 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
34d90 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
34da0 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
34db0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  sion()]..*/.SQLI
34dc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34dd0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34de0 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
34df0 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
34e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34e10 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
34e20 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
34e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
34e40 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
34e50 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
34e60 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
34e70 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
34e80 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34e90 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34ea0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
34eb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34ec0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
34ed0 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
34ee0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
34ef0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
34f00 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
34f10 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
34f20 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
34f30 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
34f40 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
34f50 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
34f60 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
34f70 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
34f80 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
34f90 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
34fa0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
34fb0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
34fc0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
34fd0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
34fe0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
34ff0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
35000 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
35010 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
35020 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
35030 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
35040 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
35050 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
35060 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
35070 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
35080 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35090 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
350a0 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
350b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
350c0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
350d0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
350e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
350f0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35100 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
35110 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
35120 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35130 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
35140 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
35150 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
35160 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
35170 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
35180 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
35190 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
351a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
351b0 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
351c0 63 61 6c 6c 65 64 20 61 20 22 76 69 72 74 75 61  called a "virtua
351d0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
351e0 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
351f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35200 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
35210 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
35220 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
35230 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
35240 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
35250 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76  dule..**.** ^A v
35260 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
35270 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
35280 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
35290 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
352a0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
352b0 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
352c0 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
352d0 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
352e0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
352f0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
35300 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
35310 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
35320 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61  ** ^The registra
35330 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c  tion remains val
35340 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  id until it is r
35350 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66  eplaced by a dif
35360 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65  ferent.** module
35370 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64   or until the [d
35380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35390 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65  on] closes.  The
353a0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74   content.** of t
353b0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75  his structure mu
353c0 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68  st not change wh
353d0 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74  ile it is regist
353e0 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79  ered with.** any
353f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35400 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  tion..*/.struct 
35410 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
35420 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
35430 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
35440 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
35450 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
35460 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
35470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
35480 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
35490 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
354a0 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
354b0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
354c0 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
354d0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
354e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
354f0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
35500 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
35510 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35520 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
35530 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
35540 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
35550 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
35560 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
35570 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
35580 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
35590 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
355a0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
355b0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
355c0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
355d0 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
355e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
355f0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
35600 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
35610 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
35620 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
35630 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
35640 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
35650 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35660 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
35670 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
35680 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
35690 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
356a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
356b0 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
356c0 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
356d0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
356e0 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
356f0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
35700 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
35710 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
35720 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
35730 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
35740 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
35750 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35760 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
35770 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
35780 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
35790 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
357a0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
357b0 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
357c0 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
357d0 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
357e0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
357f0 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
35800 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35810 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
35820 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
35830 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
35840 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
35850 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35860 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
35870 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
35880 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
35890 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
358a0 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
358b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
358c0 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
358d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
358e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
358f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
35900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35910 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
35920 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
35930 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35940 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
35950 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
35960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
35970 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
35980 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
35990 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
359a0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
359b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
359c0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
359d0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
359e0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
359f0 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
35a00 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
35a10 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
35a20 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
35a30 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
35a40 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
35a50 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
35a60 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
35a70 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
35a80 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
35a90 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
35aa0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
35ab0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
35ac0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
35ad0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
35ae0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
35af0 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
35b00 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
35b10 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
35b20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
35b30 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
35b40 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
35b50 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
35b60 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
35b70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
35b80 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
35b90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
35ba0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
35bb0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
35bc0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
35bd0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
35be0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
35bf0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
35c00 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
35c10 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
35c20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
35c30 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
35c40 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35c50 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
35c60 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
35c70 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
35c80 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
35c90 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
35ca0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
35cb0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
35cc0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
35cd0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
35ce0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
35cf0 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
35d00 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
35d10 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
35d20 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
35d30 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
35d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
35d50 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
35d60 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
35d70 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
35d80 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
35d90 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
35da0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
35db0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
35dc0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
35dd0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
35de0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
35df0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
35e00 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
35e10 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
35e20 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
35e30 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
35e40 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
35e50 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
35e60 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
35e70 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
35e80 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
35e90 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
35ea0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
35eb0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
35ec0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
35ed0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
35ee0 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
35ef0 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
35f00 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
35f10 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
35f20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
35f30 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
35f40 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
35f50 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
35f60 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
35f70 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
35f80 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
35f90 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
35fa0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
35fb0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
35fc0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
35fd0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35fe0 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
35ff0 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
36000 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
36010 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
36020 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
36030 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
36040 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
36050 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
36060 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
36070 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
36080 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
36090 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
360a0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
360b0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
360c0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
360d0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
360e0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
360f0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
36100 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
36110 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
36120 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
36130 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
36140 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
36150 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
36160 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
36170 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
36180 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
36190 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
361a0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
361b0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
361c0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
361d0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
361e0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
361f0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
36200 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
36210 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
36220 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
36230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
36240 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
36250 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
36260 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
36270 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
36280 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
36290 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
362a0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
362b0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
362c0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
362d0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
362e0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
362f0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
36300 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
36310 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
36320 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
36330 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36340 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
36350 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
36360 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
36370 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
36380 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
36390 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
363a0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
363b0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
363c0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
363d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
363e0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
363f0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
36400 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
36410 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
36420 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
36430 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
36440 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
36450 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
36460 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
36470 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
36480 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
36490 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
364a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
364b0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
364c0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
364d0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
364e0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
364f0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
36500 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
36510 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
36520 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
36530 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36540 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
36550 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
36560 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
36570 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36580 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
36590 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
365a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
365b0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
365c0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
365d0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
365e0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
365f0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
36600 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
36610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36620 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
36630 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
36640 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
36650 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36660 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
36670 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
36680 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
36690 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
366a0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
366b0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
366c0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
366d0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
366e0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
366f0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
36700 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
36710 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
36720 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
36730 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
36740 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
36750 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
36760 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
36770 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
36780 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
36790 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
367a0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
367b0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
367c0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
367d0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
367e0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
367f0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
36800 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
36810 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
36820 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
36830 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
36840 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
36850 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
36860 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
36870 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
36880 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
36890 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
368a0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
368b0 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70  le Constraint Op
368c0 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a  erator Codes.**.
368d0 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
368e0 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f  defined the allo
368f0 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74  wed values for t
36900 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  he.** [sqlite3_i
36910 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73  ndex_info].aCons
36920 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
36930 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72  d.  Each value r
36940 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20  epresents.** an 
36950 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73  operator that is
36960 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74   part of a const
36970 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68  raint term in th
36980 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e wHERE clause o
36990 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61  f.** a query tha
369a0 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61  t uses a [virtua
369b0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65  l table]..*/.#de
369c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
369d0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
369e0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
369f0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36a00 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
36a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36a20 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
36a30 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
36a40 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36a50 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
36a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
36a70 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
36a80 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
36a90 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36aa0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
36ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36ac0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
36ad0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
36ae0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  entation.**.** ^
36af0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36b00 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
36b10 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
36b20 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
36b30 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
36b40 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
36b50 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
36b60 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
36b70 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
36b80 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
36b90 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
36ba0 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
36bb0 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
36bc0 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
36bd0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
36be0 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
36bf0 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
36c00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36c10 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
36c20 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
36c30 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
36c40 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
36c50 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
36c60 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
36c70 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
36c80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
36c90 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
36ca0 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
36cb0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
36cc0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
36cd0 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
36ce0 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
36cf0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
36d00 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
36d10 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
36d20 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
36d30 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
36d40 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
36d50 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
36d60 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
36d70 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
36d80 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
36d90 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
36da0 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
36db0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
36dc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
36dd0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
36de0 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
36df0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
36e00 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
36e10 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
36e20 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
36e30 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
36e40 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
36e50 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
36e60 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
36e70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
36e80 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
36e90 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
36ea0 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
36eb0 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74  nter.  ^The dest
36ec0 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f  ructor will also
36ed0 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69  .** be invoked i
36ee0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
36ef0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36f00 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ule_v2() fails..
36f10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36f20 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a  create_module().
36f30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
36f40 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71  equivalent to sq
36f50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36f60 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ule_v2() with a 
36f70 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74  NULL.** destruct
36f80 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  or..*/.SQLITE_AP
36f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36fa0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
36fb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36fc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
36fd0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
36fe0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
36ff0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
37000 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
37010 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
37020 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
37030 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
37040 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
37050 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
37060 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
37070 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
37080 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
37090 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
370a0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
370b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
370c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
370d0 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69  odule_v2(.  sqli
370e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
370f0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
37100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
37110 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
37120 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
37130 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
37140 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
37150 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
37160 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
37170 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
37180 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
37190 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
371a0 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20  ClientData,     
371b0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
371c0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
371d0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69  Connect */.  voi
371e0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
371f0 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c  d*)     /* Modul
37200 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
37210 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ction */.);../*.
37220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
37230 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61  tual Table Insta
37240 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  nce Object.** KE
37250 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
37260 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  vtab.**.** Every
37270 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
37280 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
37290 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
372a0 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69  bclass.** of thi
372b0 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63  s object to desc
372c0 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
372d0 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
372e0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
372f0 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
37300 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
37310 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
37320 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
37330 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
37340 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
37350 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
37360 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
37370 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
37380 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
37390 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
373a0 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
373b0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
373c0 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c  ** ^Virtual tabl
373d0 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
373e0 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
373f0 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
37400 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
37410 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37420 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
37430 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
37440 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
37450 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
37460 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
37470 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
37480 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37490 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
374a0 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
374b0 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
374c0 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74  rrMsg.  ^After t
374d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
374e0 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
374f0 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
37500 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
37510 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
37520 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
37530 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
37540 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
37550 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
37560 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
37570 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37580 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
37590 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
375a0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
375b0 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
375c0 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
375d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
375e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
375f0 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
37600 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
37610 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
37620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37630 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
37640 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
37650 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
37660 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
37670 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
37680 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
37690 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
376a0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
376b0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
376c0 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
376d0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
376e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
376f0 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62  sor {virtual tab
37700 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a  le cursor}.**.**
37710 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
37720 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
37730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
37740 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
37750 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
37760 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
37770 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37780 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37790 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  he.** [virtual t
377a0 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73  able] and are us
377b0 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
377c0 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
377d0 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
377e0 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
377f0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
37800 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e  te3_module.xOpen
37810 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64   | xOpen] method
37820 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61   of the module a
37830 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  nd are destroyed
37840 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69  .** by the [sqli
37850 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73  te3_module.xClos
37860 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68  e | xClose] meth
37870 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  od.  Cursors are
37880 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
37890 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78  [xFilter], [xNex
378a0 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f  t], [xEof], [xCo
378b0 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77  lumn], and [xRow
378c0 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  id] methods.** o
378d0 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
378e0 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
378f0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
37900 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
37910 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
37920 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
37930 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
37940 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
37950 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
37960 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
37970 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
37980 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
37990 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
379a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
379b0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
379c0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
379d0 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
379e0 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
379f0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
37a00 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
37a10 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
37a20 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
37a30 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
37a40 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
37a50 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
37a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37a70 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65  Declare The Sche
37a80 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20  ma Of A Virtual 
37a90 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Table.**.** ^The
37aa0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
37ab0 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
37ac0 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75  s of a.** [virtu
37ad0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
37ae0 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72   call this inter
37af0 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61  face.** to decla
37b00 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74  re the format (t
37b10 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74  he names and dat
37b20 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f  atypes of the co
37b30 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65  lumns) of.** the
37b40 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
37b50 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a  they implement..
37b60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37b70 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
37b80 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
37b90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51   const char *zSQ
37ba0 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  L);../*.** CAPI3
37bb0 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20  REF: Overload A 
37bc0 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56  Function For A V
37bd0 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
37be0 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62  ** ^(Virtual tab
37bf0 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
37c00 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
37c10 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
37c20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
37c30 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63  g the [xFindFunc
37c40 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  tion] method of 
37c50 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
37c60 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a  le module].  .**
37c70 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
37c80 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
37c90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
37ca0 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
37cb0 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
37cc0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
37cd0 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
37ce0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
37cf0 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
37d00 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
37d10 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
37d20 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
37d30 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
37d40 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
37d50 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
37d60 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
37d70 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
37d80 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20  n is created.)^ 
37d90 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
37da0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37db0 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
37dc0 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
37dd0 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
37de0 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
37df0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
37e00 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
37e10 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
37e20 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
37e30 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
37e40 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
37e50 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
37e60 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
37e70 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  by a [virtual ta
37e80 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ble]..*/.SQLITE_
37e90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37ea0 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f  overload_functio
37eb0 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  n(sqlite3*, cons
37ec0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d  t char *zFuncNam
37ed0 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f  e, int nArg);../
37ee0 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
37ef0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
37f00 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
37f10 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20  m defined above 
37f20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61  (back up.** to a
37f30 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61   comment remarka
37f40 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  bly similar to t
37f50 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72  his one) is curr
37f60 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
37f70 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
37f80 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
37f90 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
37fa0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
37fb0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
37fc0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
37fd0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
37fe0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
37ff0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
38000 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
38010 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
38020 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
38030 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
38040 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
38050 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
38060 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
38070 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
38080 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
38090 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
380a0 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
380b0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b  n Open BLOB.** K
380c0 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68  EYWORDS: {BLOB h
380d0 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e  andle} {BLOB han
380e0 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  dles}.**.** An i
380f0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
38100 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
38110 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f  s an open BLOB o
38120 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  n which.** [sqli
38130 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
38140 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
38150 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72   I/O] can be per
38160 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65  formed..** ^Obje
38170 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
38180 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20   are created by 
38190 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
381a0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73  en()].** and des
381b0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
381c0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
381d0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
381e0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
381f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
38200 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
38210 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
38220 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
38230 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
38240 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42  ections of the B
38250 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  LOB..** ^The [sq
38260 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
38270 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
38280 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
38290 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79  f the BLOB in by
382a0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
382b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
382c0 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
382d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
382e0 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
382f0 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
38300 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  /O.**.** ^(This 
38310 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
38320 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20   a [BLOB handle 
38330 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65  | handle] to the
38340 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a   BLOB located.**
38350 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
38360 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
38370 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
38380 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
38390 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
383a0 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61  he same BLOB tha
383b0 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
383c0 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
383d0 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
383e0 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
383f0 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
38400 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a  [rowid] = iRow;.
38410 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
38420 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20  * ^If the flags 
38430 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
38440 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
38450 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
38460 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77  or read.** and w
38470 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66  rite access. ^If
38480 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
38490 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
384a0 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e  for read access.
384b0 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70  .** ^It is not p
384c0 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
384d0 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
384e0 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65   part of an inde
384f0 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a  x or primary .**
38500 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67   key for writing
38510 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b  . ^If [foreign k
38520 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20  ey constraints] 
38530 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20  are enabled, it 
38540 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69  is .** not possi
38550 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
38560 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
38570 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65  t of a [child ke
38580 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a  y] for writing..
38590 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
385a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
385b0 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69  me is not the fi
385c0 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74  lename that cont
385d0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  ains.** the data
385e0 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20  base but rather 
385f0 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
38600 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
38610 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72  e that.** appear
38620 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b  s after the AS k
38630 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20  eyword when the 
38640 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
38650 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
38660 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68  ACH]..** ^For th
38670 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
38680 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61  file, the databa
38690 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e  se name is "main
386a0 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20  "..** ^For TEMP 
386b0 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61  tables, the data
386c0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65  base name is "te
386d0 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  mp"..**.** ^(On 
386e0 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
386f0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
38700 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c   and the new [BL
38710 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  OB handle] is wr
38720 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42  itten.** to *ppB
38730 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61  lob. Otherwise a
38740 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
38750 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a  s returned and *
38760 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a  ppBlob is set.**
38770 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f   to be a null po
38780 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69  inter.)^.** ^Thi
38790 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
387a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
387b0 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
387c0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
387d0 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
387e0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
387f0 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
38800 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
38810 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
38820 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68  ctions. ^Note th
38830 61 74 20 74 68 65 20